brainclaw 0.29.2 → 1.5.3

package/dist/commands/plan-resource.js

@@ -2,6 +2,9 @@ import { runPlan } from './plan.js';
 import { runListPlans } from './list-plans.js';
 import { runUpdatePlan } from './update-plan.js';
 import { runDeletePlan } from './delete-plan.js';
+import { loadState } from '../core/state.js';
+import { memoryExists } from '../core/io.js';
+const KNOWN_SUBCOMMANDS = new Set(['create', 'list', 'ls', 'update', 'delete', 'show', 'get']);
 export function runPlanResource(subcommand, args, options = {}) {
     const normalized = subcommand.trim().toLowerCase();
     if (normalized === 'create') {
@@ -21,9 +24,21 @@ export function runPlanResource(subcommand, args, options = {}) {
             assignee: options.assignee,
             project: options.project,
             all: options.all,
+            recursive: options.recursive,
+            localOnly: options.localOnly,
         });
         return;
     }
+    if (normalized === 'show' || normalized === 'get') {
+        const id = args[0];
+        if (!id) {
+            console.error(`Error: plan ${normalized} requires <id>.`);
+            console.error(`  Usage: brainclaw plan ${normalized} <id>`);
+            process.exit(1);
+        }
+        runShowPlan(id, options);
+        return;
+    }
     if (normalized === 'update') {
         const id = args[0];
         if (!id) {
@@ -51,6 +66,12 @@ export function runPlanResource(subcommand, args, options = {}) {
         runDeletePlan(id, { cwd: options.cwd });
         return;
     }
+    // Reject known-looking subcommands to prevent accidental plan creation
+    if (normalized.startsWith('pln_') || KNOWN_SUBCOMMANDS.has(normalized)) {
+        console.error(`Error: unknown plan subcommand "${subcommand}".`);
+        console.error('  Available: create, list, show, get, update, delete');
+        process.exit(1);
+    }
     // Compatibility path: `brainclaw plan "text"` still creates a plan.
     const legacyText = [subcommand, ...args].join(' ').trim();
     if (!legacyText) {
@@ -59,4 +80,47 @@ export function runPlanResource(subcommand, args, options = {}) {
     }
     runPlan(legacyText, options);
 }
+function runShowPlan(id, options) {
+    if (!memoryExists(options.cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const state = loadState(options.cwd);
+    const plan = state.plan_items.find(p => p.id === id);
+    if (!plan) {
+        console.error(`Error: plan not found: ${id}`);
+        process.exit(1);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(plan, null, 2));
+        return;
+    }
+    console.log(`Plan: ${plan.id}`);
+    console.log(`  Text:     ${plan.text}`);
+    console.log(`  Status:   ${plan.status}`);
+    if (plan.type)
+        console.log(`  Type:     ${plan.type}`);
+    if (plan.priority)
+        console.log(`  Priority: ${plan.priority}`);
+    if (plan.assignee)
+        console.log(`  Assignee: ${plan.assignee}`);
+    if (plan.project)
+        console.log(`  Project:  ${plan.project}`);
+    if (plan.estimated_effort)
+        console.log(`  Estimate: ${plan.estimated_effort}min`);
+    if (plan.actual_effort)
+        console.log(`  Actual:   ${plan.actual_effort}`);
+    if (plan.tags && plan.tags.length > 0)
+        console.log(`  Tags:     ${plan.tags.join(', ')}`);
+    console.log(`  Created:  ${plan.created_at}`);
+    if (plan.updated_at)
+        console.log(`  Updated:  ${plan.updated_at}`);
+    if (plan.steps && plan.steps.length > 0) {
+        console.log('  Steps:');
+        for (const step of plan.steps) {
+            const check = step.status === 'done' ? '✔' : '○';
+            console.log(`    ${check} ${step.text}`);
+        }
+    }
+}
 //# sourceMappingURL=plan-resource.js.map

package/dist/commands/plan.js

@@ -1,21 +1,17 @@
-import { loadState, persistState } from '../core/state.js';
 import { resolveCurrentAgentName } from '../core/agent-registry.js';
 import { loadConfig } from '../core/config.js';
-import { generateIdWithLabel, nowISO } from '../core/ids.js';
 import { scanText } from '../core/security.js';
-import { memoryExists } from '../core/io.js';
+import { requireInitialized } from '../core/guards.js';
 import { validateCliInput } from '../core/input-validation.js';
 import { runListPlans } from './list-plans.js';
 import { resolveTargetStore } from '../core/store-resolution.js';
+import { createPlan } from '../core/operations/plan.js';
 // Known plan subcommands that should not be accepted as plan text
 const PLAN_SUBCOMMAND_ALIASES = new Set(['list', 'ls']);
 const PLAN_SUBCOMMAND_ERRORS = new Set(['update']);
 export function runPlan(text, options = {}) {
     const cwd = resolveTargetStore(options.cwd ?? process.cwd(), options.store ?? 'local');
-    if (!memoryExists(cwd)) {
-        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
-        process.exit(1);
-    }
+    requireInitialized(cwd);
     const normalized = text.trim().toLowerCase();
     if (PLAN_SUBCOMMAND_ALIASES.has(normalized)) {
         runListPlans({});
@@ -46,29 +42,19 @@ export function runPlan(text, options = {}) {
         }
         estimatedEffort = n;
     }
-    const state = loadState(cwd);
-    const { id, short_label } = generateIdWithLabel('plan_items');
-    const timestamp = nowISO();
-    const entry = {
-        id,
-        short_label,
+    const result = createPlan({
         text,
-        type: options.type,
-        created_at: timestamp,
-        updated_at: timestamp,
         author: options.author ?? resolveCurrentAgentName(cwd),
-        status: 'todo',
-        priority: options.priority ?? 'medium',
+        type: options.type,
+        priority: options.priority,
         assignee: options.assignee,
         project: options.project,
-        tags: options.tag ?? [],
-        related_paths: options.path,
-        depends_on: options.dependsOn ?? [],
-        estimated_effort: estimatedEffort,
-    };
-    state.plan_items.push(entry);
-    persistState(state, cwd);
+        tags: options.tag,
+        relatedPaths: options.path,
+        dependsOn: options.dependsOn,
+        estimatedEffort,
+    }, cwd);
     const storeLabel = options.store && options.store !== 'local' ? ` [store:${options.store}]` : '';
-    console.log(`✔ Plan item added: [${id}] ${text}${storeLabel}`);
+    console.log(`✔ Plan item added: [${result.id}] ${text}${storeLabel}`);
 }
 //# sourceMappingURL=plan.js.map

package/dist/commands/prune.js

@@ -4,12 +4,36 @@ import { mutate } from '../core/mutation-pipeline.js';
 import { rebuildProjectMd } from '../core/markdown.js';
 import { deleteRuntimeNote, listRuntimeNotes } from '../core/runtime.js';
 import { expireStaleActiveClaims } from '../core/claims.js';
+import { archiveStalePlansAndHandoffs } from '../core/archival.js';
+import { rotateAuditLogIfNeeded } from '../core/audit.js';
+import { analyzeMemory, analyzeAndApply, formatReport } from '../core/memory-compactor.js';
 export function runPrune(options = {}) {
     const cwd = process.cwd();
     if (!memoryExists(cwd)) {
         console.error('Project memory not initialized. Run `brainclaw init` first.');
         process.exit(1);
     }
+    // Semantic compaction mode
+    if (options.semantic) {
+        if (options.dryRun) {
+            // Dry-run: read-only analysis, no lock needed
+            const state = loadState(cwd);
+            const report = analyzeMemory(state, { cwd });
+            console.log(formatReport(report));
+            return;
+        }
+        // Apply: analyze + apply atomically under a single mutation lock
+        const { report, result } = analyzeAndApply({ cwd });
+        if (report.archivableCount === 0) {
+            console.log('No compaction opportunities found.');
+            return;
+        }
+        console.log(formatReport(report));
+        console.log('');
+        console.log(`✔ Compaction applied: ${result.archivedCount} items archived (${result.mergedClusters} clusters merged, ${result.staleArchived} stale items).`);
+        return;
+    }
+    // Original prune logic
     const now = new Date().toISOString();
     let prunedCount = 0;
     let expiredClaimsCount = 0;
@@ -41,11 +65,22 @@ export function runPrune(options = {}) {
         }
         rebuildProjectMd(loadState(cwd), cwd);
     });
+    // Archive and rotate outside the mutation lock (they manage their own IO)
+    let archiveMsg = '';
+    if (options.archive) {
+        const archiveResults = archiveStalePlansAndHandoffs(cwd);
+        if (archiveResults.length > 0) {
+            const parts = archiveResults.map(r => `${r.archived} ${r.entity}`);
+            archiveMsg = `, archived ${parts.join(' + ')} to cold storage`;
+        }
+    }
+    const rotated = rotateAuditLogIfNeeded(cwd);
+    const rotateMsg = rotated ? ', rotated audit.log' : '';
     if (options.expired) {
-        console.log(`✔ Pruned ${prunedCount} expired constraints, ${expiredNotesCount} expired runtime notes, ${expiredClaimsCount} expired claims.`);
+        console.log(`✔ Pruned ${prunedCount} expired constraints, ${expiredNotesCount} expired runtime notes, ${expiredClaimsCount} expired claims${archiveMsg}${rotateMsg}.`);
     }
     else {
-        console.log(`✔ Pruned ${prunedCount} expired constraints, ${expiredClaimsCount} expired claims.`);
+        console.log(`✔ Pruned ${prunedCount} expired constraints, ${expiredClaimsCount} expired claims${archiveMsg}${rotateMsg}.`);
     }
 }
 //# sourceMappingURL=prune.js.map

package/dist/commands/reflect.js

@@ -8,8 +8,8 @@ import { scanText } from '../core/security.js';
 import { nowISO, generateIdWithLabel } from '../core/ids.js';
 import { saveCandidate, generateCandidateIdWithLabel, listCandidates } from '../core/candidates.js';
 import { detectDuplicates } from '../core/duplicates.js';
-import { RuntimeEventSchema } from '../core/schema.js';
-import { listRuntimeEventsBySession } from '../core/events.js';
+import { CandidateSourceSchema, RuntimeEventSchema } from '../core/schema.js';
+import { isReflectableRuntimeEvent, listRuntimeEventsBySession } from '../core/events.js';
 import { agentCanWriteDirect, requireMinimumTrustLevel, requireRegisteredAgentIdentity } from '../core/agent-registry.js';
 import { appendAuditEntry } from '../core/audit.js';
 import { generateTrapIdWithLabel } from '../core/traps.js';
@@ -56,6 +56,9 @@ function runReflectBatchFromFile(filepath, baseOptions) {
     for (const rawEvent of rawEvents) {
         try {
             const event = RuntimeEventSchema.parse(rawEvent);
+            if (!isReflectableRuntimeEvent(event)) {
+                continue;
+            }
             const candidateType = event.candidate_type ?? mapEventTypeToCandidateType(event.event_type);
             createCandidateFromInput(event.text, candidateType, {
                 ...baseOptions,
@@ -87,6 +90,9 @@ function runReflectBatchFromSession(session, baseOptions) {
     }
     let created = 0;
     for (const event of events) {
+        if (!isReflectableRuntimeEvent(event)) {
+            continue;
+        }
         const candidateType = event.candidate_type ?? mapEventTypeToCandidateType(event.event_type);
         createCandidateFromInput(event.text, candidateType, {
             ...baseOptions,
@@ -158,7 +164,14 @@ export function createCandidateFromInput(text, type, options, printSuccess = tru
         project_id: options.projectId ?? actorIdentity.project_id,
         host_id: options.hostId ?? actorIdentity.host_id,
         session_id: options.sessionId ?? actorIdentity.session_id,
-        source: options.source,
+        // Normalize source to the enum when possible; otherwise infer from the
+        // free-text origin value below. Preserves legacy provenance patterns
+        // (runtime-note:*, mcp:*, session-end:*, cross-project:*) in `origin`
+        // while keeping `source` strictly enum-constrained.
+        source: CandidateSourceSchema.safeParse(options.source).data,
+        origin: typeof options.source === 'string' && !CandidateSourceSchema.safeParse(options.source).success
+            ? options.source
+            : undefined,
         tags: options.tag ?? [],
         status: 'pending',
         severity: type === 'trap' ? options.severity ?? 'medium' : undefined,
@@ -238,28 +251,28 @@ function promoteCandidateToState(candidate, cwd) {
     switch (candidate.type) {
         case 'constraint': {
             const { id: cId, short_label } = generateIdWithLabel('active_constraints', cwd);
-            const entry = { id: cId, 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 };
+            const entry = { id: cId, 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, plan_id: candidate.plan_id };
             state.active_constraints.push(entry);
             promotedItemId = entry.id;
             break;
         }
         case 'decision': {
             const { id: dId, short_label } = generateIdWithLabel('recent_decisions', cwd);
-            const entry = { id: dId, 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, tags: candidate.tags };
+            const entry = { id: dId, 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 = entry.id;
             break;
         }
         case 'trap': {
             const { id: tId, short_label } = generateTrapIdWithLabel(cwd);
-            const entry = { id: tId, 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, visibility: 'shared' };
+            const entry = { id: tId, 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 = entry.id;
             break;
         }
         case 'handoff': {
             const { id: hId, short_label } = generateIdWithLabel('open_handoffs', cwd);
-            const entry = { id: hId, 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, from: candidate.from ?? '', to: candidate.to ?? '', status: 'open', tags: candidate.tags, related_paths: candidate.related_paths };
+            const entry = { id: hId, 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, from: candidate.from ?? '', to: candidate.to ?? '', status: 'open', tags: candidate.tags, plan_id: candidate.plan_id, narrative: candidate.narrative, related_paths: candidate.related_paths };
             state.open_handoffs.push(entry);
             promotedItemId = entry.id;
             break;

package/dist/commands/release-claim.js

@@ -2,7 +2,7 @@ import { memoryExists } from '../core/io.js';
 import { mutate } from '../core/mutation-pipeline.js';
 import { loadClaim, listClaims, releaseClaim } from '../core/claims.js';
 import { rebuildProjectMd } from '../core/markdown.js';
-import { loadState, saveState } from '../core/state.js';
+import { loadState, mutateState } from '../core/state.js';
 export function runReleaseClaim(id, options = {}) {
     if (!memoryExists(options.cwd)) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
@@ -13,10 +13,12 @@ export function runReleaseClaim(id, options = {}) {
         mutate({ cwd: options.cwd }, () => {
             const existing = loadClaim(id, options.cwd);
             claim = releaseClaim(id, options.cwd);
-            let state = loadState(options.cwd);
             if (existing.plan_id) {
-                const plan = state.plan_items.find((item) => item.id === existing.plan_id);
-                if (plan) {
+                const updated = mutateState((state) => {
+                    const plan = state.plan_items.find((item) => item.id === existing.plan_id);
+                    if (!plan) {
+                        return false;
+                    }
                     const otherActiveClaims = listClaims(options.cwd).filter((item) => item.status === 'active' && item.plan_id === existing.plan_id);
                     if (options.planStatus) {
                         plan.status = options.planStatus;
@@ -28,10 +30,13 @@ export function runReleaseClaim(id, options = {}) {
                         plan.assignee = undefined;
                     }
                     plan.updated_at = new Date().toISOString();
-                    saveState(state, options.cwd);
+                    return true;
+                }, options.cwd, { writeProjectMarkdown: false });
+                if (updated) {
+                    const state = loadState(options.cwd);
+                    rebuildProjectMd(state, options.cwd);
                 }
             }
-            rebuildProjectMd(state, options.cwd);
         });
         console.log(`✔ Claim [${id}] released (was: ${claim.agent} → ${claim.scope})`);
     }

package/dist/commands/release-notes.js

@@ -0,0 +1,170 @@
+import { execSync } from 'node:child_process';
+import { loadConfig } from '../core/config.js';
+import { memoryExists } from '../core/io.js';
+import { checkBrainclawInstallableUpdate, getInstalledBrainclawVersion, } from '../core/brainclaw-version.js';
+/**
+ * Generate agent-first release notes from git log since a given ref.
+ * Returns structured notes suitable for --agent-release-notes.
+ */
+export function generateAgentReleaseNotes(cwd, since) {
+    const version = getInstalledBrainclawVersion();
+    const baseRef = since ?? findLastVersionTag(cwd) ?? 'HEAD~20';
+    let commits;
+    try {
+        const raw = execSync(`git log ${baseRef}..HEAD --oneline --no-decorate`, {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 10000,
+        });
+        commits = raw.split('\n').map((l) => l.trim()).filter(Boolean);
+    }
+    catch {
+        commits = [];
+    }
+    if (commits.length === 0) {
+        return {
+            summary: `Brainclaw ${version} — no changes since last release.`,
+            breaking_risk: 'none',
+            action_recommendation: 'No update needed.',
+        };
+    }
+    const highlights = categorizeCommits(commits);
+    const hasBreaking = commits.some((c) => /breaking|BREAKING/i.test(c));
+    const hasFix = commits.some((c) => /^[a-f0-9]+ fix/i.test(c));
+    const hasFeat = commits.some((c) => /^[a-f0-9]+ feat/i.test(c));
+    const summaryParts = [];
+    if (hasFeat)
+        summaryParts.push('new features');
+    if (hasFix)
+        summaryParts.push('bug fixes');
+    if (!hasFeat && !hasFix)
+        summaryParts.push('improvements');
+    const summary = `Brainclaw ${version} — ${summaryParts.join(' and ')} (${commits.length} commits).`;
+    const breakingRisk = hasBreaking ? 'high' : hasFeat ? 'low' : 'none';
+    return {
+        summary,
+        agent_relevance: hasFeat
+            ? 'New capabilities available — review highlights for agent workflow improvements.'
+            : hasFix
+                ? 'Bug fixes that may affect agent reliability.'
+                : 'Maintenance release.',
+        breaking_risk: breakingRisk,
+        recommended_for: hasBreaking ? ['operators'] : ['all'],
+        highlights: highlights.slice(0, 5),
+        action_recommendation: hasBreaking
+            ? 'Review breaking changes before updating. Operator confirmation recommended.'
+            : 'Safe to update. No operator confirmation needed.',
+    };
+}
+function findLastVersionTag(cwd) {
+    try {
+        const tag = execSync('git describe --tags --abbrev=0 HEAD', {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return tag.length > 0 ? tag : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function categorizeCommits(commits) {
+    const highlights = [];
+    const seen = new Set();
+    for (const commit of commits) {
+        // Strip hash prefix
+        const msg = commit.replace(/^[a-f0-9]+\s+/, '');
+        const category = extractCategory(msg);
+        if (category && !seen.has(category)) {
+            seen.add(category);
+            highlights.push(msg);
+        }
+    }
+    // If not enough categorized, add uncategorized ones
+    if (highlights.length < 5) {
+        for (const commit of commits) {
+            const msg = commit.replace(/^[a-f0-9]+\s+/, '');
+            if (!highlights.includes(msg)) {
+                highlights.push(msg);
+                if (highlights.length >= 5)
+                    break;
+            }
+        }
+    }
+    return highlights;
+}
+function extractCategory(msg) {
+    const match = /^(feat|fix|chore|test|docs|refactor|perf|ci|build)\b/i.exec(msg);
+    return match?.[1]?.toLowerCase();
+}
+export function runReleaseNotes(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (options.generate) {
+        const notes = generateAgentReleaseNotes(cwd, options.since);
+        if (options.json) {
+            console.log(JSON.stringify(notes, null, 2));
+        }
+        else {
+            console.log(`Summary: ${notes.summary}`);
+            if (notes.agent_relevance)
+                console.log(`Agent relevance: ${notes.agent_relevance}`);
+            console.log(`Breaking risk: ${notes.breaking_risk ?? 'none'}`);
+            if (notes.recommended_for?.length)
+                console.log(`Recommended for: ${notes.recommended_for.join(', ')}`);
+            if (notes.highlights?.length) {
+                console.log('Highlights:');
+                for (const h of notes.highlights)
+                    console.log(`  • ${h}`);
+            }
+            if (notes.action_recommendation)
+                console.log(`Action: ${notes.action_recommendation}`);
+        }
+        return;
+    }
+    // Show current release notes from configured update source
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const config = loadConfig(cwd);
+    const updateCheck = checkBrainclawInstallableUpdate(config, cwd, { useDefaultNpmSource: true });
+    const arn = updateCheck.agent_release_notes;
+    if (options.json) {
+        console.log(JSON.stringify({
+            status: updateCheck.status,
+            latest_installable_version: updateCheck.latest_installable_version,
+            agent_release_notes: arn ?? null,
+            release_notes: updateCheck.release_notes ?? null,
+        }, null, 2));
+        return;
+    }
+    if (arn) {
+        console.log(`Version: ${updateCheck.latest_installable_version ?? 'unknown'}`);
+        console.log(`Summary: ${arn.summary}`);
+        if (arn.agent_relevance)
+            console.log(`Agent relevance: ${arn.agent_relevance}`);
+        console.log(`Breaking risk: ${arn.breaking_risk ?? 'none'}`);
+        if (arn.recommended_for?.length)
+            console.log(`Recommended for: ${arn.recommended_for.join(', ')}`);
+        if (arn.highlights?.length) {
+            console.log('Highlights:');
+            for (const h of arn.highlights)
+                console.log(`  • ${h}`);
+        }
+        if (arn.action_recommendation)
+            console.log(`Action: ${arn.action_recommendation}`);
+    }
+    else if (updateCheck.release_notes) {
+        console.log(`Version: ${updateCheck.latest_installable_version ?? 'unknown'}`);
+        console.log(updateCheck.release_notes);
+    }
+    else {
+        console.log('No agent release notes available for the configured update source.');
+        if (updateCheck.status === 'not_configured') {
+            console.log('Configure brainclaw_update_source in your project config to enable update checks.');
+        }
+    }
+}
+//# sourceMappingURL=release-notes.js.map