brainclaw 1.9.0 → 1.9.1

package/docs/server-operations.md

@@ -1,118 +1,118 @@
-# Server And Remote Operations
-
-This guide is for complex operator environments such as DGX hosts, remote Linux servers, SSH-driven workflows, and multi-project workspaces where Brainclaw is not being used from a single local IDE.
-
-## When this guide matters
-
-Use this path when one or more of these are true:
-
-- Brainclaw runs on a remote machine over SSH
-- multiple repos or child projects live under one server workspace
-- different agents resume each other over time on the same host
-- the operator sometimes uses CLI directly instead of MCP
-
-## Recommended baseline
-
-Prefer a disciplined single-environment workflow on the server:
-
-1. choose one canonical checkout per active task
-2. initialize Brainclaw in the target project before starting coordination work
-3. avoid mixing multiple shells, PATH setups, or Node installations during the same session
-4. treat shared-checkout parallel editing as risky unless each session gets a dedicated worktree
-
-## Multi-project targeting
-
-If the server workspace contains several Brainclaw projects, resolve the target project first.
-
-```bash
-brainclaw switch --list
-brainclaw switch apps/trainer
-brainclaw status
-```
-
-You can also use:
-
-- `BRAINCLAW_PROJECT` for a shell-scoped default
-- `brainclaw --cwd <path> ...` for a one-off override
-
-The goal is to avoid writing memory into the wrong store when the operator is launched from a workspace root.
-
-## Recommended session flow
-
-For MCP-capable agents:
-
-1. `bclaw_work(intent="execute", scope=...)` — opens a session, loads context, and claims the scope (with a per-claim git worktree) in a single call. Returns a compact payload by default; pass `compact: false` for the full memory dump or call `bclaw_context(kind="memory")` after.
-2. `bclaw_context(kind="execution")` — when local tooling / brainclaw version visibility is needed (already loaded implicitly by `bclaw_work`).
-3. `bclaw_write_note` / `bclaw_create(entity=...)` / `bclaw_update(entity=...)` — record observations, plans, decisions, or traps via the canonical grammar.
-4. `bclaw_session_end(narrative=..., auto_release: true)` — close cleanly; releases active claims and hands off the session record.
-
-For direct CLI operation:
-
-```bash
-brainclaw session-start --agent codex
-brainclaw plan list --all
-brainclaw claim create "Investigate training config drift" --scope configs/training/
-brainclaw runtime-note "Observed host-specific CUDA mismatch on dgx-a"
-brainclaw session-end --auto-release
-```
-
-`brainclaw runtime-note` is the CLI equivalent of `bclaw_write_note`.
-`brainclaw note create "..."` is accepted as a resource-style alias if that fits the operator workflow better.
-
-## Isolation and worktrees
-
-The safest default remains sequential collaboration: one active agent per checkout, then handoff.
-
-If you need stronger isolation:
-
-```bash
-brainclaw worktree create feat/dgx-audit
-brainclaw worktree list
-```
-
-In MCP flows, `bclaw_claim` can also create a dedicated worktree automatically when supported by the current Brainclaw version and configuration.
-
-Use dedicated worktrees when:
-
-- two sessions need to touch the same repo without sharing a checkout
-- an operator wants to preserve a clean main checkout while an agent runs elsewhere
-- a remote machine hosts long-lived or resumable agent sessions
-
-## Plan and step semantics
-
-Be explicit about the difference between plan items and plan steps:
-
-- `brainclaw plan show <id>` reads a single plan item
-- `brainclaw plan get <id>` is accepted as a read alias, but `brainclaw plan show <id>` remains the canonical form
-- `brainclaw plan update <id>` expects a `pln_*` plan ID
-- `brainclaw complete-step <planId> <stepId>` is the canonical way to complete a step
-
-If you only have a step ID, inspect the parent plan first with `plan show` or `plan list --json`.
-
-## Notes, decisions, and traps
-
-Do not use `decision` as a workaround for a session observation.
-
-Use:
-
-- `brainclaw runtime-note` for in-session observations
-- `brainclaw reflect-runtime-note` when the note may deserve promotion
-- `brainclaw decision` only for a durable decision
-- `brainclaw trap` only for a reusable pitfall
-
-This keeps canonical memory cleaner on long-lived server projects.
-
-## Common failure modes
-
-- Wrong project selected: use `brainclaw switch --list` and verify `brainclaw status`
-- Shared-checkout collisions: prefer a worktree per session when parallel activity is unavoidable
-- Confusion between plan IDs and step IDs: use `plan show` before `plan update`
-- Lost operator observations: record them with `runtime-note` instead of temporary shell notes
-
-## Recommended reading
-
-- [quickstart.md](quickstart.md)
-- [cli.md](cli.md)
-- [integrations/mcp.md](integrations/mcp.md)
-- [concepts/plans-and-claims.md](concepts/plans-and-claims.md)
-- [concepts/runtime-notes.md](concepts/runtime-notes.md)
+# Server And Remote Operations
+
+This guide is for complex operator environments such as DGX hosts, remote Linux servers, SSH-driven workflows, and multi-project workspaces where Brainclaw is not being used from a single local IDE.
+
+## When this guide matters
+
+Use this path when one or more of these are true:
+
+- Brainclaw runs on a remote machine over SSH
+- multiple repos or child projects live under one server workspace
+- different agents resume each other over time on the same host
+- the operator sometimes uses CLI directly instead of MCP
+
+## Recommended baseline
+
+Prefer a disciplined single-environment workflow on the server:
+
+1. choose one canonical checkout per active task
+2. initialize Brainclaw in the target project before starting coordination work
+3. avoid mixing multiple shells, PATH setups, or Node installations during the same session
+4. treat shared-checkout parallel editing as risky unless each session gets a dedicated worktree
+
+## Multi-project targeting
+
+If the server workspace contains several Brainclaw projects, resolve the target project first.
+
+```bash
+brainclaw switch --list
+brainclaw switch apps/trainer
+brainclaw status
+```
+
+You can also use:
+
+- `BRAINCLAW_PROJECT` for a shell-scoped default
+- `brainclaw --cwd <path> ...` for a one-off override
+
+The goal is to avoid writing memory into the wrong store when the operator is launched from a workspace root.
+
+## Recommended session flow
+
+For MCP-capable agents:
+
+1. `bclaw_work(intent="execute", scope=...)` — opens a session, loads context, and claims the scope (with a per-claim git worktree) in a single call. Returns a compact payload by default; pass `compact: false` for the full memory dump or call `bclaw_context(kind="memory")` after.
+2. `bclaw_context(kind="execution")` — when local tooling / brainclaw version visibility is needed (already loaded implicitly by `bclaw_work`).
+3. `bclaw_write_note` / `bclaw_create(entity=...)` / `bclaw_update(entity=...)` — record observations, plans, decisions, or traps via the canonical grammar.
+4. `bclaw_session_end(narrative=..., auto_release: true)` — close cleanly; releases active claims and hands off the session record.
+
+For direct CLI operation:
+
+```bash
+brainclaw session-start --agent codex
+brainclaw plan list --all
+brainclaw claim create "Investigate training config drift" --scope configs/training/
+brainclaw runtime-note "Observed host-specific CUDA mismatch on dgx-a"
+brainclaw session-end --auto-release
+```
+
+`brainclaw runtime-note` is the CLI equivalent of `bclaw_write_note`.
+`brainclaw note create "..."` is accepted as a resource-style alias if that fits the operator workflow better.
+
+## Isolation and worktrees
+
+The safest default remains sequential collaboration: one active agent per checkout, then handoff.
+
+If you need stronger isolation:
+
+```bash
+brainclaw worktree create feat/dgx-audit
+brainclaw worktree list
+```
+
+In MCP flows, `bclaw_claim` can also create a dedicated worktree automatically when supported by the current Brainclaw version and configuration.
+
+Use dedicated worktrees when:
+
+- two sessions need to touch the same repo without sharing a checkout
+- an operator wants to preserve a clean main checkout while an agent runs elsewhere
+- a remote machine hosts long-lived or resumable agent sessions
+
+## Plan and step semantics
+
+Be explicit about the difference between plan items and plan steps:
+
+- `brainclaw plan show <id>` reads a single plan item
+- `brainclaw plan get <id>` is accepted as a read alias, but `brainclaw plan show <id>` remains the canonical form
+- `brainclaw plan update <id>` expects a `pln_*` plan ID
+- `brainclaw complete-step <planId> <stepId>` is the canonical way to complete a step
+
+If you only have a step ID, inspect the parent plan first with `plan show` or `plan list --json`.
+
+## Notes, decisions, and traps
+
+Do not use `decision` as a workaround for a session observation.
+
+Use:
+
+- `brainclaw runtime-note` for in-session observations
+- `brainclaw reflect-runtime-note` when the note may deserve promotion
+- `brainclaw decision` only for a durable decision
+- `brainclaw trap` only for a reusable pitfall
+
+This keeps canonical memory cleaner on long-lived server projects.
+
+## Common failure modes
+
+- Wrong project selected: use `brainclaw switch --list` and verify `brainclaw status`
+- Shared-checkout collisions: prefer a worktree per session when parallel activity is unavoidable
+- Confusion between plan IDs and step IDs: use `plan show` before `plan update`
+- Lost operator observations: record them with `runtime-note` instead of temporary shell notes
+
+## Recommended reading
+
+- [quickstart.md](quickstart.md)
+- [cli.md](cli.md)
+- [integrations/mcp.md](integrations/mcp.md)
+- [concepts/plans-and-claims.md](concepts/plans-and-claims.md)
+- [concepts/runtime-notes.md](concepts/runtime-notes.md)

package/docs/storage.md

@@ -1,110 +1,110 @@
-# Storage Model
-
-brainclaw is local-first and workspace-centric.
-
-## Default structure
-
-```text
-.brainclaw/
-  config.yaml                    ← Project configuration
+# Storage Model
+
+brainclaw is local-first and workspace-centric.
+
+## Default structure
+
+```text
+.brainclaw/
+  config.yaml                    ← Project configuration
   project.md                     ← Legacy derived readable view (best-effort, regenerable)
-  events.jsonl                   ← Append-only event log (agent notifications)
-  audit.log                      ← Append-only audit trail (before/after snapshots)
-  memory/
-    constraints/                 ← Canonical constraint entries (one JSON per entity)
-    decisions/                   ← Canonical decision entries
-    traps/                       ← Canonical trap entries
-    instructions/                ← Layered shared instructions
-  coordination/
-    plans/                       ← Shared plan items
-    claims/                      ← Active scope claims
-    handoffs/                    ← Handoff records
-    sessions/                    ← Session state
-    runtime/                     ← Runtime notes (shared, machine, private)
-    inbox/                       ← Candidate review queue
-  discovery/
-    bootstrap/                   ← Bootstrap profiles and seeds
-  agents/                        ← Agent registration and identity
-```
-
-## Design principles
-
-### Canonical state is split
-Each entity is stored as its own JSON file (e.g. `memory/decisions/dec_abc123.json`).
-
-Benefits:
-
-- readable diffs in `.brainclaw/.git`
-- easier merges
-- clear provenance per entity
-- O(1) lookup by ID (direct file access)
-- no giant monolithic memory blob
-- isolated corruption (one bad file does not affect others)
-
-### Derived views are best-effort
+  events.jsonl                   ← Append-only event log (agent notifications)
+  audit.log                      ← Append-only audit trail (before/after snapshots)
+  memory/
+    constraints/                 ← Canonical constraint entries (one JSON per entity)
+    decisions/                   ← Canonical decision entries
+    traps/                       ← Canonical trap entries
+    instructions/                ← Layered shared instructions
+  coordination/
+    plans/                       ← Shared plan items
+    claims/                      ← Active scope claims
+    handoffs/                    ← Handoff records
+    sessions/                    ← Session state
+    runtime/                     ← Runtime notes (shared, machine, private)
+    inbox/                       ← Candidate review queue
+  discovery/
+    bootstrap/                   ← Bootstrap profiles and seeds
+  agents/                        ← Agent registration and identity
+```
+
+## Design principles
+
+### Canonical state is split
+Each entity is stored as its own JSON file (e.g. `memory/decisions/dec_abc123.json`).
+
+Benefits:
+
+- readable diffs in `.brainclaw/.git`
+- easier merges
+- clear provenance per entity
+- O(1) lookup by ID (direct file access)
+- no giant monolithic memory blob
+- isolated corruption (one bad file does not affect others)
+
+### Derived views are best-effort
 `.brainclaw/project.md` is a **legacy derived view** regenerated from canonical state via `rebuildProjectMd()`. It is not a write target and no longer carries live claims, plans, handoffs, or runtime state — use `brainclaw agent-board`, `brainclaw context`, or MCP board/context tools for that operational data.
 
 Root `PROJECT.md` is different: it is the durable project vision and should contain stable product, architecture, and contribution guidance that does not expire every session.
-
-Failures to regenerate `project.md` are logged but never block mutations. If it gets stale, `brainclaw doctor` detects the drift.
-
-### All mutations go through a single pipeline
-Every write to `.brainclaw/` is serialized through `mutate()` (`src/core/mutation-pipeline.ts`):
-
-1. **Store-wide lock** — advisory file lock at `.brainclaw/.store-mutation` (5s timeout, 10s expiry)
-2. **Reentrant** — nested mutations within the same process are safe
-3. **Atomic writes** — individual files use temp-file + rename pattern
-4. **Git versioned** — `.brainclaw/.git` tracks all changes for rollback
-
-For agents using MCP (the recommended path), mutations are additionally serialized by the MCP server's `McpTaskRunner` — a FIFO queue that runs one task at a time. This provides two layers of write safety:
-
-| Layer | Scope | Mechanism |
-|---|---|---|
-| **McpTaskRunner** | Single MCP server process | FIFO queue, one active Worker thread |
-| **mutate() file lock** | Cross-process (CLI + MCP) | Advisory `.store-mutation` lock file |
-
-Agents should always use MCP tools for mutations. The CLI is for human operators, scripting, and fallback workflows.
-
-### Topology can vary
-
-Depending on configuration, storage may be:
-
-| Topology | Behavior |
-|---|---|
-| `embedded` (default) | `.brainclaw/` inside the repo, tracked by Git |
-| `sidecar` | `.brainclaw/` inside the repo but gitignored |
-| `local-only` | Outside the repo, never tracked |
-
-## What belongs in canonical memory
-
-- decisions
-- constraints
-- traps
-- layered instructions
-- handoffs
-- plans
-
-## What stays operational
-
-- machine-local runtime notes
-- private notes
-- short-lived observations (with optional TTL)
-- reflective candidates awaiting review
-- event log and audit trail
-
-## Why this model matters
-
-The storage model is part of the product value:
-
-- local-first — no cloud dependency
-- inspectable — plain text + JSON
-- Git-friendly — entity-per-file, readable diffs
-- reversible — `.brainclaw/.git` history + rollback
-- mutation-safe — serialized writes, atomic file operations
-- suitable for both humans and agents
-
-## Related pages
-
-- [concepts/memory.md](concepts/memory.md)
-- [concepts/runtime-notes.md](concepts/runtime-notes.md)
-- [security.md](security.md)
+
+Failures to regenerate `project.md` are logged but never block mutations. If it gets stale, `brainclaw doctor` detects the drift.
+
+### All mutations go through a single pipeline
+Every write to `.brainclaw/` is serialized through `mutate()` (`src/core/mutation-pipeline.ts`):
+
+1. **Store-wide lock** — advisory file lock at `.brainclaw/.store-mutation` (5s timeout, 10s expiry)
+2. **Reentrant** — nested mutations within the same process are safe
+3. **Atomic writes** — individual files use temp-file + rename pattern
+4. **Git versioned** — `.brainclaw/.git` tracks all changes for rollback
+
+For agents using MCP (the recommended path), mutations are additionally serialized by the MCP server's `McpTaskRunner` — a FIFO queue that runs one task at a time. This provides two layers of write safety:
+
+| Layer | Scope | Mechanism |
+|---|---|---|
+| **McpTaskRunner** | Single MCP server process | FIFO queue, one active Worker thread |
+| **mutate() file lock** | Cross-process (CLI + MCP) | Advisory `.store-mutation` lock file |
+
+Agents should always use MCP tools for mutations. The CLI is for human operators, scripting, and fallback workflows.
+
+### Topology can vary
+
+Depending on configuration, storage may be:
+
+| Topology | Behavior |
+|---|---|
+| `embedded` (default) | `.brainclaw/` inside the repo, tracked by Git |
+| `sidecar` | `.brainclaw/` inside the repo but gitignored |
+| `local-only` | Outside the repo, never tracked |
+
+## What belongs in canonical memory
+
+- decisions
+- constraints
+- traps
+- layered instructions
+- handoffs
+- plans
+
+## What stays operational
+
+- machine-local runtime notes
+- private notes
+- short-lived observations (with optional TTL)
+- reflective candidates awaiting review
+- event log and audit trail
+
+## Why this model matters
+
+The storage model is part of the product value:
+
+- local-first — no cloud dependency
+- inspectable — plain text + JSON
+- Git-friendly — entity-per-file, readable diffs
+- reversible — `.brainclaw/.git` history + rollback
+- mutation-safe — serialized writes, atomic file operations
+- suitable for both humans and agents
+
+## Related pages
+
+- [concepts/memory.md](concepts/memory.md)
+- [concepts/runtime-notes.md](concepts/runtime-notes.md)
+- [security.md](security.md)

package/package.json

@@ -1,71 +1,86 @@
-{
-  "name": "brainclaw",
-  "version": "1.9.0",
-  "description": "Shared project memory for humans and coding agents.",
-  "type": "module",
-  "bin": {
-    "brainclaw": "dist/cli.js",
-    "bclaw": "dist/cli.js"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/core/default-profiles/*.yaml",
-    "dist/brainclaw-vscode.vsix",
-    "dist/facts.json",
-    "docs/**/*.md",
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "scripts": {
-    "clean:build": "node scripts/clean-build.mjs dist dist-test",
-    "clean:dist": "node scripts/clean-build.mjs dist",
-    "clean:dist-test": "node scripts/clean-build.mjs dist-test",
+{
+  "name": "brainclaw",
+  "version": "1.9.1",
+  "description": "Shared project memory for humans and coding agents.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jberdah/brainclaw.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jberdah/brainclaw/issues"
+  },
+  "homepage": "https://brainclaw.dev",
+  "bin": {
+    "brainclaw": "dist/cli.js",
+    "bclaw": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/core/default-profiles/*.yaml",
+    "dist/brainclaw-vscode.vsix",
+    "dist/facts.json",
+    "docs/**/*.md",
+    "!docs/concepts/*proposal*.md",
+    "!docs/concepts/*critique*.md",
+    "!docs/concepts/*phase0-measurements*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "clean:build": "node scripts/clean-build.mjs dist dist-test",
+    "clean:dist": "node scripts/clean-build.mjs dist",
+    "clean:dist-test": "node scripts/clean-build.mjs dist-test",
     "build": "npm run build:cli && node scripts/build-vsix.mjs --optional",
     "build:cli": "npm run clean:dist && tsc && node scripts/copy-default-profiles.mjs",
     "build:release": "npm run build:cli && node scripts/emit-site-facts.mjs && node scripts/build-vsix.mjs",
     "emit:facts": "npm run build:cli && node scripts/emit-site-facts.mjs",
-    "dev": "npm run clean:dist && tsc && node scripts/copy-default-profiles.mjs && node dist/cli.js",
-    "dev:mcp": "tsc && node scripts/copy-default-profiles.mjs",
-    "build:mcp-schemas": "npm run clean:dist && tsc && node scripts/build-mcp-schemas.mjs",
-    "dev:link": "npm link && echo 'Symlink created: global brainclaw → local repo. MCP agents now use dist/ directly.'",
+    "dev": "npm run clean:dist && tsc && node scripts/copy-default-profiles.mjs && node dist/cli.js",
+    "dev:mcp": "tsc && node scripts/copy-default-profiles.mjs",
+    "build:mcp-schemas": "npm run clean:dist && tsc && node scripts/build-mcp-schemas.mjs",
+    "dev:link": "npm link && echo 'Symlink created: global brainclaw → local repo. MCP agents now use dist/ directly.'",
     "build:test": "npm run build:cli && npm run clean:dist-test && tsc -p tsconfig.test.json",
-    "pack:check": "node scripts/check-pack.mjs",
-    "test": "npm run build:test && node scripts/run-tests.mjs default",
-    "test:unit": "npm run build:test && node scripts/run-tests.mjs unit",
-    "test:smoke": "npm run build:test && node scripts/run-tests.mjs smoke",
-    "test:e2e": "npm run build:test && node scripts/run-tests.mjs e2e",
-    "test:all": "npm run build:test && node scripts/run-tests.mjs all",
-    "test:cross": "npm run build:test && node scripts/test-cross.mjs default",
-    "test:coverage": "npm run build:test && c8 --all --src dist-test/src --reporter=text-summary --reporter=lcov --exclude=dist-test/tests/** --exclude=dist-test/scripts/** node scripts/run-tests.mjs default",
-    "test:coverage:check": "npm run build:test && c8 --all --check-coverage --lines 55 --functions 60 --branches 65 --statements 55 --src dist-test/src --reporter=text-summary --exclude=dist-test/tests/** --exclude=dist-test/scripts/** node scripts/run-tests.mjs default",
+    "pack:check": "node scripts/check-pack.mjs",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "npm run build:test && node scripts/run-tests.mjs default",
+    "test:unit": "npm run build:test && node scripts/run-tests.mjs unit",
+    "test:smoke": "npm run build:test && node scripts/run-tests.mjs smoke",
+    "test:e2e": "npm run build:test && node scripts/run-tests.mjs e2e",
+    "test:all": "npm run build:test && node scripts/run-tests.mjs all",
+    "test:cross": "npm run build:test && node scripts/test-cross.mjs default",
+    "test:coverage": "npm run build:test && c8 --all --src dist-test/src --reporter=text-summary --reporter=lcov --exclude=dist-test/tests/** --exclude=dist-test/scripts/** node scripts/run-tests.mjs default",
+    "test:coverage:check": "npm run build:test && c8 --all --check-coverage --lines 55 --functions 60 --branches 65 --statements 55 --src dist-test/src --reporter=text-summary --exclude=dist-test/tests/** --exclude=dist-test/scripts/** node scripts/run-tests.mjs default",
     "prepublishOnly": "npm run build:release && npm run pack:check"
-  },
-  "keywords": [
-    "cli",
-    "memory",
-    "agents",
-    "coding-agents",
-    "project-context",
-    "handoff",
-    "local-first"
-  ],
-  "license": "MIT",
-  "homepage": "https://brainclaw.dev",
-  "dependencies": {
-    "commander": "^14.0.3",
-    "yaml": "^2.7.1",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^24.12.2",
-    "ajv": "^8.20.0",
-    "c8": "^11.0.0",
-    "typescript": "^6.0.3"
-  }
-}
+  },
+  "keywords": [
+    "cli",
+    "memory",
+    "agents",
+    "coding-agents",
+    "project-context",
+    "handoff",
+    "local-first"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^14.0.3",
+    "yaml": "^2.7.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.12.2",
+    "ajv": "^8.20.0",
+    "c8": "^11.0.0",
+    "eslint": "^10.5.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.1"
+  }
+}