brainclaw 1.15.0 → 1.16.0

package/README.md

@@ -255,8 +255,10 @@ bclaw_coordinate({
   targetAgents: ["claude-code"] 
 });
 
-// 4. The loop progresses as agents interact and resolve findings
-bclaw_loop({ intent: "advance", loop_id: "lop_abc" });
+// 4. The reviewer's verdict is harvested from its LANE-RESULT.json and the loop
+//    auto-closes on approve — no manual advance needed for the approve path.
+//    (bclaw_loop remains available to drive the request_changes fix cycle by hand.)
+bclaw_loop({ intent: "get", loop_id: "lop_abc" }); // inspect status any time
 ```
 
 ## The Loop Engine (Multi-Turn Workflows)
@@ -268,6 +270,8 @@ Brainclaw's Loop Engine moves beyond manual ping-pong by formalizing multi-turn
 
 Each loop maintains a structured lifecycle, explicit phases, iteration bounds, and per-phase memory filters, executed seamlessly via `bclaw_loop`.
 
+**Autonomous convergence (pln#628 Focus 4B):** a dispatched reviewer doesn't need to be driven by hand. It writes its verdict (`review_verdict: approve | request_changes`) into its `LANE-RESULT.json`; when the coordinator harvests the lane, brainclaw records the verdict on the loop and **auto-closes it on approve** — the review loop reaches `reviewer_green` with no human ping-pong. `request_changes` advances to the author phase (the automated fix→re-review cycle is a planned follow-up).
+
 ## Enterprise Ready: Mono-repo & Micro-services
 
 Brainclaw is designed to scale across complex environments. Using the **`project_mode`** setting, Brainclaw seamlessly auto-detects folder boundaries for mono-repos and applies proper environment bootstrapping.
@@ -306,7 +310,7 @@ Recent releases have moved a lot of multi-agent parallel work from "risky" to "s
 
 - **Per-claim auto-worktree** — each dispatched lane gets its own isolated git worktree; the coordinator integrates with an octopus merge.
 - **Sequenced parallel execute** — `bclaw_dispatch(intent="execute")` fans out independent lanes across several agent instances and integrates the result.
-- **Symmetric review-fix loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="symmetric")` runs an alternating review-and-fix conversation across two slots without shared-checkout collisions.
+- **Symmetric review-fix loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="symmetric")` runs an alternating review-and-fix conversation across two slots without shared-checkout collisions. The reviewer's verdict is harvested from `LANE-RESULT.json` and the loop **auto-closes on approve** — no manual round-trip to converge the approve path.
 - **Cross-platform spawn** — OS-aware prompt delivery (stdin pipe / inline arg) plus a brief-ack file handshake, so spawned workers can be detected and timed out reliably on Windows and Unix.
 - **Worktree GC is scope-bounded** — symlinks and junctions are no longer followed during cleanup, so post-merge sweeps can't wipe `node_modules` or other neighboring directories.
 - **MCP runtime self-heal** — when the runtime is corrupted, the server logs an actionable repair pointer; `brainclaw doctor --repair` rebuilds dist in one step.
@@ -315,6 +319,7 @@ Still sharp:
 
 1. **Same-checkout concurrent edits** — running two agents in the *same* working tree (no per-claim worktree) is still the wrong answer. Use the dispatch path (auto-worktree per claim) instead of raw concurrent CLI sessions.
 2. **Cross-machine sync** — federation across machines is on the roadmap, not in v1.x. Today brainclaw's store is local and one-machine-per-project.
+3. **Next.js / Turbopack dev server in a worktree** — the provisioned `node_modules` symlink points outside the worktree root, which `next dev` (Turbopack) rejects (build/tsc/vitest are fine). brainclaw warns; `npm install` in the worktree or smoke-test on the merged branch. A Turbopack-compatible dependency mode is a planned follow-up.
 3. **Spawn-and-forget assumptions** — spawned workers don't always commit their work cleanly. The brief-ack file confirms the spawn started; in the worst case the coordinator harvests open changes.
 4. **Live state for hook-less agents** — supported hook-less file surfaces such as Cline, Windsurf, Continue, Antigravity/Gemini CLI, and Mistral Vibe can get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
 
@@ -344,6 +349,8 @@ Maven, Gradle, and Cargo are intentionally excluded — their dependency caches
 
 Build outputs like `dist` are **not** symlinked — they must be per-worktree to avoid EBUSY errors when other processes hold handles on the output directory.
 
+> **Next.js / Turbopack caveat.** The `node_modules` link is a symlink to the main worktree, i.e. it points **outside** the agent worktree's root. `tsc`, `vitest`, and production `build` follow it fine, but `next dev` (Turbopack) panics on a `node_modules` link outside the worktree root. brainclaw detects Next.js projects and surfaces a `symlink_warnings` note at worktree creation. Workaround for dev-server work: run `npm install` inside the worktree (optionally with `BRAINCLAW_NO_LINK_DEPS=1`), or smoke-test on the merged branch. A Turbopack-compatible per-worktree dependency mode is a planned follow-up.
+
 Override detection in `.brainclaw/config.yaml`:
 
 ```yaml

package/dist/cli/register-capture.js

@@ -0,0 +1,209 @@
+import { runDecision } from '../commands/decision.js';
+import { runConstraint } from '../commands/constraint.js';
+import { runTrap } from '../commands/trap.js';
+import { runHandoff } from '../commands/handoff.js';
+import { runUpdateHandoff } from '../commands/update-handoff.js';
+import { runReflect } from '../commands/reflect.js';
+import { runReflectRuntimeNote } from '../commands/reflect-runtime-note.js';
+import { runInstruction } from '../commands/instruction.js';
+import { runListInstructions } from '../commands/list-instructions.js';
+import { runRuntimeNote } from '../commands/runtime-note.js';
+import { runRuntimeStatus } from '../commands/runtime-status.js';
+import { collect } from './shared.js';
+export function registerCaptureCommands(program) {
+    // --- decision ---
+    program
+        .command('decision <text>')
+        .description('Add a recent decision')
+        .option('--outcome <outcome>', 'Outcome: approved, rejected, deferred, pending')
+        .option('--tag <tags...>', 'Tags for this decision')
+        .option('--path <paths...>', 'Related file paths')
+        .option('--author <author>', 'Author name')
+        .option('--plan <id>', 'Optional linked plan item ID')
+        .option('--store <target>', 'Target store level: local (default), repo, workspace, user')
+        .action((text, options) => {
+        runDecision(text, options);
+    });
+    // --- constraint ---
+    program
+        .command('constraint <text>')
+        .description('Add an active constraint')
+        .option('--category <category>', 'Category: architecture, performance, security, reliability, compatibility, process, other')
+        .option('--tag <tags...>', 'Tags for this constraint')
+        .option('--path <paths...>', 'Related file paths')
+        .option('--author <author>', 'Author name')
+        .option('--store <target>', 'Target store level: local (default), repo, workspace, user')
+        .action((text, options) => {
+        runConstraint(text, options);
+    });
+    // --- trap ---
+    program
+        .command('trap <text>')
+        .description('Add a known trap')
+        .option('--status <status>', 'Status: active, resolved, expired', 'active')
+        .option('--severity <severity>', 'Severity: low, medium, high', 'medium')
+        .option('--visibility <visibility>', 'Visibility: shared, machine, private', 'shared')
+        .option('--host <host>', 'Optional host identifier override for machine/private traps')
+        .option('--tag <tags...>', 'Tags for this trap')
+        .option('--path <paths...>', 'Related file paths')
+        .option('--author <author>', 'Author name')
+        .option('--ttl <duration>', 'Time-to-live: 30m, 2h, 7d (trap auto-expires after this duration)')
+        .option('--store <target>', 'Target store level: local (default), repo, workspace, user')
+        .action((text, options) => {
+        runTrap(text, options);
+    });
+    // --- handoff ---
+    program
+        .command('handoff <text>')
+        .description('Create a handoff')
+        .requiredOption('--from <from>', 'Source of the handoff')
+        .requiredOption('--to <to>', 'Destination of the handoff')
+        .option('--tag <tags...>', 'Tags for this handoff')
+        .option('--path <paths...>', 'Related file paths')
+        .option('--project <project>', 'Optional project namespace')
+        .option('--plan <id>', 'Optional linked plan item ID')
+        .option('--author <author>', 'Author name')
+        .option('--capture-diff', 'Capture current git diff into the handoff snapshot')
+        .option('--files <files...>', 'Files touched in this handoff')
+        .option('--pre-condition <conditions...>', 'Pre-conditions for the receiving agent')
+        .option('--post-condition <conditions...>', 'Post-conditions the receiving agent must satisfy')
+        .option('--test <tests...>', 'Tests the receiving agent should verify')
+        .option('--linked-plan <plans...>', 'Linked plan IDs')
+        .action((text, options) => {
+        runHandoff(text, options);
+    });
+    // --- update-handoff ---
+    program
+        .command('update-handoff <id>')
+        .description('Update the status, recipient, or review state of a handoff')
+        .option('--status <status>', 'Status: open, accepted, closed')
+        .option('--to <agent>', 'Change the receiving agent')
+        .option('--narrative <text>', 'Update the narrative attached to the handoff')
+        .option('--reviewer <agent>', 'Set or override the assigned reviewer')
+        .option('--review-verdict <verdict>', 'Set review verdict: approve or request_changes')
+        .option('--reviewed-by <agent>', 'Set the reviewer identity that produced the verdict')
+        .option('--review-summary <text>', 'Attach a short review summary')
+        .option('--blocking-issue <text>', 'Add a blocking review issue (repeatable)', collect, [])
+        .option('--suggestion <text>', 'Add a non-blocking review suggestion (repeatable)', collect, [])
+        .action((id, options) => {
+        runUpdateHandoff(id, {
+            ...options,
+            review_verdict: options.reviewVerdict,
+            reviewed_by: options.reviewedBy,
+            review_summary: options.reviewSummary,
+            blocking_issues: options.blockingIssue,
+            suggestions: options.suggestion,
+        });
+    });
+    // --- reflect ---
+    program
+        .command('reflect [text]')
+        .description('Create a memory candidate for review')
+        .option('--type <type>', 'Type: constraint, decision, trap, handoff')
+        .option('--batch <file>', 'Import runtime events from JSON file')
+        .option('--session <id>', 'Import runtime events by session id from .brainclaw/runtime/')
+        .option('--tag <tags...>', 'Tags')
+        .option('--author <author>', 'Author name')
+        .option('--source <source>', 'Source context (e.g. agent name)')
+        .option('--severity <severity>', 'Severity for traps: low, medium, high')
+        .option('--from <from>', 'Handoff source')
+        .option('--to <to>', 'Handoff destination')
+        .option('--path <paths...>', 'Related file paths')
+        .action((text, options) => {
+        runReflect(text, options);
+    });
+    // --- reflect-runtime-note ---
+    program
+        .command('reflect-runtime-note <id> [text]')
+        .description('Turn a visible runtime note into a shared review candidate')
+        .option('--type <type>', 'Type: constraint, decision, trap, handoff')
+        .option('--host <host>', 'Look up machine-local runtime note for a specific host')
+        .option('--all-hosts', 'Look up runtime notes across all hosts')
+        .option('--suggest', 'Show candidate type suggestions before or instead of creation')
+        .option('--json', 'Output suggestions as JSON when used with --suggest or without --type')
+        .option('--tag <tags...>', 'Additional tags to merge with the runtime note tags')
+        .option('--author <author>', 'Author name for the candidate')
+        .option('--source <source>', 'Source context for the candidate')
+        .option('--severity <severity>', 'Severity for traps: low, medium, high')
+        .option('--from <from>', 'Handoff source')
+        .option('--to <to>', 'Handoff destination')
+        .option('--path <paths...>', 'Related file paths')
+        .action((id, text, options) => {
+        runReflectRuntimeNote(id, text, options);
+    });
+    // --- instruction ---
+    program
+        .command('instruction <text>')
+        .description('Add a layered shared instruction')
+        .option('--layer <layer>', 'Instruction layer: global, project, agent', 'global')
+        .option('--project <project>', 'Project namespace when --layer project is used')
+        .option('--agent <agent>', 'Agent name when --layer agent is used')
+        .option('--tag <tags...>', 'Tags for this instruction')
+        .option('--author <author>', 'Author name')
+        .option('--supersedes <id>', 'Supersede an older instruction entry')
+        .option('--store <target>', 'Target store level: local (default), repo, workspace, user')
+        .action((text, options) => {
+        runInstruction(text, options);
+    });
+    // --- list-instructions ---
+    program
+        .command('list-instructions')
+        .description('List raw or resolved shared instructions')
+        .option('--json', 'Output as JSON')
+        .option('--layer <layer>', 'Filter by layer: global, project, agent')
+        .option('--project <project>', 'Project namespace filter')
+        .option('--agent <agent>', 'Agent name filter')
+        .option('--active', 'Only show active entries')
+        .option('--resolved', 'Resolve effective instructions for the given scope')
+        .option('--for <target>', 'Infer project namespace from target path when strategy=folder')
+        .action((options) => {
+        runListInstructions(options);
+    });
+    // --- runtime-note ---
+    program
+        .command('runtime-note <text>')
+        .description('Add a runtime note for an agent')
+        .option('--agent <agent>', 'Agent name; defaults to the configured current agent')
+        .option('--project <project>', 'Optional project namespace')
+        .option('--plan <id>', 'Optional linked plan item ID')
+        .option('--visibility <visibility>', 'Visibility: shared, machine, private', 'shared')
+        .option('--host <host>', 'Optional host identifier override for machine/private runtime notes')
+        .option('--tag <tags...>', 'Tags')
+        .option('--ttl <duration>', 'Time-to-live: 30m, 2h, 7d (note auto-expires after this duration)')
+        .option('--auto-reflect', 'Attempt to turn this runtime note into durable memory immediately')
+        .action((text, options) => {
+        runRuntimeNote(text, { ...options, autoReflect: options.autoReflect });
+    });
+    // --- note create ---
+    const noteCommand = program
+        .command('note')
+        .description('Manage runtime notes');
+    noteCommand
+        .command('create <text>')
+        .description('Alias for runtime-note')
+        .option('--agent <agent>', 'Agent name; defaults to the configured current agent')
+        .option('--project <project>', 'Optional project namespace')
+        .option('--plan <id>', 'Optional linked plan item ID')
+        .option('--visibility <visibility>', 'Visibility: shared, machine, private', 'shared')
+        .option('--host <host>', 'Optional host identifier override for machine/private runtime notes')
+        .option('--tag <tags...>', 'Tags')
+        .option('--ttl <duration>', 'Time-to-live: 30m, 2h, 7d (note auto-expires after this duration)')
+        .option('--auto-reflect', 'Attempt to turn this runtime note into durable memory immediately')
+        .action((text, options) => {
+        runRuntimeNote(text, { ...options, autoReflect: options.autoReflect });
+    });
+    // --- runtime-status ---
+    program
+        .command('runtime-status')
+        .description('Show runtime notes')
+        .option('--agent <agent>', 'Filter by agent')
+        .option('--plan <id>', 'Filter by linked plan item')
+        .option('--visibility <visibility>', 'Visibility filter: shared, machine, private, all')
+        .option('--host <host>', 'Include machine-local notes for a specific host')
+        .option('--all-hosts', 'Include machine-local notes from all hosts')
+        .option('--json', 'Output as JSON')
+        .action((options) => {
+        runRuntimeStatus(options);
+    });
+}
+//# sourceMappingURL=register-capture.js.map

package/dist/cli/register-code-map.js

@@ -0,0 +1,19 @@
+import { runCodeMap } from '../commands/code-map.js';
+export function registerCodeMapCommands(program) {
+    // --- code-map ---
+    program
+        .command('code-map <subcommand> [args...]')
+        .description('Query the per-project Code Map (status, refresh, find, brief)')
+        .option('--json', 'Output as JSON')
+        .option('--all', 'For refresh: enumerate all supported files (full refresh)')
+        .option('--changed', 'For refresh: only changed files (default)')
+        .option('--cascade', 'For refresh/status in a multi-project workspace: cascade across every nested project (each gets its own store; the root store is scoped to files no child owns)')
+        .option('--limit <n>', 'Max results for find/brief', (v) => parseInt(v, 10))
+        .action((subcommand, args, options) => {
+        void runCodeMap(subcommand, args, options).catch((err) => {
+            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        });
+    });
+}
+//# sourceMappingURL=register-code-map.js.map