brainclaw 1.8.0 → 1.9.1

package/docs/storage.md

@@ -1,108 +1,110 @@
-# Storage Model
-
-brainclaw is local-first and workspace-centric.
-
-## Default structure
-
-```text
-.brainclaw/
-  config.yaml                    ← Project configuration
-  project.md                     ← 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
-`project.md` is a **derived view** regenerated from canonical state via `rebuildProjectMd()`. It is not a write target — it can always be rebuilt from the JSON files using `brainclaw rebuild`.
-
-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)
+# 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
+`.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)

package/package.json

@@ -1,69 +1,86 @@
-{
-  "name": "brainclaw",
-  "version": "1.8.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",
-    "build": "npm run clean:dist && tsc && node scripts/copy-default-profiles.mjs && node scripts/build-vsix.mjs",
-    "build:cli": "npm run clean:dist && tsc && node scripts/copy-default-profiles.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.'",
-    "build:test": "npm run build && 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: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 && node scripts/emit-site-facts.mjs && 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"
-  }
-}
+{
+  "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.'",
+    "build:test": "npm run build:cli && npm run clean:dist-test && tsc -p tsconfig.test.json",
+    "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",
+  "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"
+  }
+}