brainclaw 1.9.0 → 1.10.0

package/docs/concepts/plans-and-claims.md

@@ -1,217 +1,217 @@
-# Plans and Claims
-
-Plans and claims are where brainclaw starts to feel less like a note system and more like a coordination layer.
-
-## Plans
-
-Plans provide a shared view of intended work.
-
-They help teams and agents answer questions like:
-
-- what are we trying to ship?
-- what is in progress?
-- what is blocked?
-- what is done?
-- who is responsible right now?
-
-### Plan statuses
-
-| Status | Meaning |
-|--------|---------|
-| `todo` | Not started yet |
-| `in_progress` | Actively being worked on |
-| `done` | Completed |
-| `blocked` | Waiting on something external |
-| `dropped` | Dropped |
-
-### Creating plans
-
-```bash
-brainclaw plan create "implement login flow"
-brainclaw plan create "refactor auth module" --priority high --estimate 120
-```
-
-The `--estimate` flag accepts a **positive integer in minutes**. Example: `--estimate 30` means 30 minutes, `--estimate 120` means 2 hours.
-
-### Updating plans
-
-```bash
-brainclaw plan update <id> --status in_progress
-brainclaw plan update <id> --status done --actual-effort 45min
-```
-
-When marking a plan `in_progress` for the first time, `started_at` is automatically recorded.
-When marking a plan `done`, `completed_at` is automatically recorded.
-
-### Plan steps
-
-Plans can have sub-steps for multi-phase work:
-
-```bash
-brainclaw add-step <plan-id> "write unit tests"
-brainclaw add-step <plan-id> "update docs"
-brainclaw complete-step <plan-id> <step-id>
-```
-
-Steps show up in `brainclaw context` and `brainclaw board` so other agents and humans can see granular progress.
-`brainclaw plan update` changes the parent plan item only; step completion is handled through `complete-step`.
-
-### Estimation and calibration
-
-When both `estimated_effort` and `actual_effort` are present on completed plans, brainclaw can compute an accuracy report:
-
-```bash
-brainclaw estimation-report
-brainclaw estimation-report --agent my-agent
-```
-
-This shows a ratio chart (actual / estimate) and a calibration hint:
-
-```
-task with estimate      est:30min  actual:45min  [ratio:1.5x]
-[0.0x    ░░░░░░░░░░│████████████████████░░░░░░░░░░░░░░░░░  2.0x+]
-                                                        OVER +50%
-```
-
-A ratio below 1.0 means the task finished faster than expected (early). Above 1.0 means it took longer (over).
-
-### Step-level estimation (pln#495)
-
-Estimation can be captured per **step**, not just per plan — which removes a real
-source of noise. A plan's wall-clock span (`created_at`→`completed_at`) counts
-the idle time *between* steps as if it were work: if steps 1–5 finish in a
-morning and step 6 lands the next day, the plan-level elapsed smears an 18h gap
-that was never effort. Summing per-step durations excludes those gaps.
-
-Set step estimates and actuals via `add-step` / `update-step`:
-
-```bash
-brainclaw add-step <plan-id> "write unit tests" --estimate 30
-brainclaw update-step <plan-id> <step-id> --status in_progress   # stamps started_at
-brainclaw update-step <plan-id> <step-id> --status done           # stamps completed_at
-# or record an explicit actual:
-brainclaw update-step <plan-id> <step-id> --actual-effort 45m
-```
-
-`estimated_effort` accepts the same forms as the plan-level `--estimate` (an
-integer of minutes, or a legacy duration string like `2h` / `30m`).
-
-`estimation-report` then prefers step-level data and tags each plan with its
-**measurement source**:
-
-- **`step`** — the highest quality: `estimated_minutes` is the sum of step
-  estimates (used only when *every* step has one), and `elapsed_minutes` is the
-  sum of per-step durations (used only when *every* step is measurable, via an
-  explicit `actual_effort` or both `started_at`+`completed_at`). Idle gaps
-  between steps are excluded.
-- **`plan_string`** — fell back to the plan-level `actual_effort` string.
-- **`plan_wallclock`** — fell back to the plan's `created_at`→`completed_at`
-  span (the noisiest; what older plans use).
-
-The report's summary breaks the median ratio down per source
-(`step-derived: 1.0x · plan-wallclock: 0.4x …`) so you can see how much
-calibration error was wall-clock contamination vs real estimation drift, and the
-chart tags each line (`✓step` / `~wall`).
-
-**Migration:** none required. A plan whose steps carry no estimation data — or a
-plan with no steps at all — keeps working exactly as before via the fallback
-chain. Mixed plans (some steps estimated, some not) fall back to plan-level
-entirely rather than reporting a misleading partial sum.
-
-## Claims
-
-Claims make current ownership explicit.
-
-A claim can represent:
-
-- a file
-- a folder
-- a feature area
-- a work scope linked to a plan item
-
-Claims help reduce collisions when multiple humans or agents work in parallel.
-
-### Creating claims
-
-```bash
-brainclaw claim create "refactoring auth module" --scope src/auth/
-brainclaw claim create "updating docs" --scope docs/ --ttl 4h
-brainclaw claim create "fixing login bug" --scope src/auth/ --plan <plan-id>
-```
-
-The `--ttl` flag sets a time-to-live for the claim. After expiry, the claim is no longer considered active by other agents. Valid formats: `30min`, `2h`, `1d`.
-
-### Listing and releasing claims
-
-```bash
-brainclaw claim list
-brainclaw claim release <id>
-```
-
-`claim list` shows who holds each claim and whether it is still active. If a claim has a `session_id`, the last 8 characters are shown so you can correlate with the agent session that created it.
-
-### Automatic claim release
-
-Claims are automatically released after a `git merge` if the post-merge hook is installed (installed by default by `brainclaw init`). The hook matches merged file paths against active claim scopes and releases overlapping claims.
-
-You can also install or reinstall the hook manually:
-
-```bash
-brainclaw install-hooks
-```
-
-## Why claims matter
-
-Without claims, multiple agents can easily touch the same area at once and generate conflicting changes.
-Claims are not necessarily hard file locks.
-They are a shared coordination signal.
-
-## Policy checks
-
-Before editing a scope, agents can verify governance compliance using `check-policy`:
-
-```bash
-brainclaw check-policy --scope src/core/auth.ts --agent claude-code
-```
-
-Or via MCP:
-
-```
-bclaw_check_policy(scope: "src/core/auth.ts", agent: "claude-code")
-```
-
-The check is fully **deterministic** (no AI involved) and verifies:
-
-- **Claim active** — Does the agent have a claim on this scope? (BLOCK if not)
-- **Claim conflict** — Is another agent claiming this scope? (BLOCK)
-- **Constraints** — Do any active constraints with matching `related_paths` apply? (WARN)
-- **Traps** — Are there known pitfalls for this scope? (WARN)
-- **Governance context** — Active global instructions are surfaced for reference.
-
-Policy warnings are also **automatically included** in the `bclaw_claim` response — agents get constraint and trap alerts at claim time without an extra call.
-
-## Recommended workflow
-
-1. create a plan item
-2. claim the target scope — `bclaw_claim` (or `bclaw_work(intent="execute", scope=…, planId=…)`) creates an isolated git worktree under `~/.brainclaw/worktrees/<project-hash>/` automatically; policy warnings are surfaced as part of the response
-3. work on the implementation inside the worktree
-4. update the plan status (`bclaw_transition(entity="plan", id, to="in_progress" | "done")`)
-5. commit and merge back; release the claim when done or blocked
-6. create a handoff if another actor should continue
-
-## Session hygiene
-
-Before finishing a session, always:
-
-- release active claims: `brainclaw claim release <id>`
-- update plan items: `brainclaw plan update <id> --status done`
-- or use `brainclaw session-end --auto-release` to clean up automatically
-
-`session-end --auto-release` releases all claims held by the current agent and marks any `in_progress` plans as needing attention.
-
-## Plans + claims together
-
-Plans describe what should happen.
-Claims describe who is currently working where.
-
-That combination is much more useful than either one alone.
+# Plans and Claims
+
+Plans and claims are where brainclaw starts to feel less like a note system and more like a coordination layer.
+
+## Plans
+
+Plans provide a shared view of intended work.
+
+They help teams and agents answer questions like:
+
+- what are we trying to ship?
+- what is in progress?
+- what is blocked?
+- what is done?
+- who is responsible right now?
+
+### Plan statuses
+
+| Status | Meaning |
+|--------|---------|
+| `todo` | Not started yet |
+| `in_progress` | Actively being worked on |
+| `done` | Completed |
+| `blocked` | Waiting on something external |
+| `dropped` | Dropped |
+
+### Creating plans
+
+```bash
+brainclaw plan create "implement login flow"
+brainclaw plan create "refactor auth module" --priority high --estimate 120
+```
+
+The `--estimate` flag accepts a **positive integer in minutes**. Example: `--estimate 30` means 30 minutes, `--estimate 120` means 2 hours.
+
+### Updating plans
+
+```bash
+brainclaw plan update <id> --status in_progress
+brainclaw plan update <id> --status done --actual-effort 45min
+```
+
+When marking a plan `in_progress` for the first time, `started_at` is automatically recorded.
+When marking a plan `done`, `completed_at` is automatically recorded.
+
+### Plan steps
+
+Plans can have sub-steps for multi-phase work:
+
+```bash
+brainclaw add-step <plan-id> "write unit tests"
+brainclaw add-step <plan-id> "update docs"
+brainclaw complete-step <plan-id> <step-id>
+```
+
+Steps show up in `brainclaw context` and `brainclaw board` so other agents and humans can see granular progress.
+`brainclaw plan update` changes the parent plan item only; step completion is handled through `complete-step`.
+
+### Estimation and calibration
+
+When both `estimated_effort` and `actual_effort` are present on completed plans, brainclaw can compute an accuracy report:
+
+```bash
+brainclaw estimation-report
+brainclaw estimation-report --agent my-agent
+```
+
+This shows a ratio chart (actual / estimate) and a calibration hint:
+
+```
+task with estimate      est:30min  actual:45min  [ratio:1.5x]
+[0.0x    ░░░░░░░░░░│████████████████████░░░░░░░░░░░░░░░░░  2.0x+]
+                                                        OVER +50%
+```
+
+A ratio below 1.0 means the task finished faster than expected (early). Above 1.0 means it took longer (over).
+
+### Step-level estimation (pln#495)
+
+Estimation can be captured per **step**, not just per plan — which removes a real
+source of noise. A plan's wall-clock span (`created_at`→`completed_at`) counts
+the idle time *between* steps as if it were work: if steps 1–5 finish in a
+morning and step 6 lands the next day, the plan-level elapsed smears an 18h gap
+that was never effort. Summing per-step durations excludes those gaps.
+
+Set step estimates and actuals via `add-step` / `update-step`:
+
+```bash
+brainclaw add-step <plan-id> "write unit tests" --estimate 30
+brainclaw update-step <plan-id> <step-id> --status in_progress   # stamps started_at
+brainclaw update-step <plan-id> <step-id> --status done           # stamps completed_at
+# or record an explicit actual:
+brainclaw update-step <plan-id> <step-id> --actual-effort 45m
+```
+
+`estimated_effort` accepts the same forms as the plan-level `--estimate` (an
+integer of minutes, or a legacy duration string like `2h` / `30m`).
+
+`estimation-report` then prefers step-level data and tags each plan with its
+**measurement source**:
+
+- **`step`** — the highest quality: `estimated_minutes` is the sum of step
+  estimates (used only when *every* step has one), and `elapsed_minutes` is the
+  sum of per-step durations (used only when *every* step is measurable, via an
+  explicit `actual_effort` or both `started_at`+`completed_at`). Idle gaps
+  between steps are excluded.
+- **`plan_string`** — fell back to the plan-level `actual_effort` string.
+- **`plan_wallclock`** — fell back to the plan's `created_at`→`completed_at`
+  span (the noisiest; what older plans use).
+
+The report's summary breaks the median ratio down per source
+(`step-derived: 1.0x · plan-wallclock: 0.4x …`) so you can see how much
+calibration error was wall-clock contamination vs real estimation drift, and the
+chart tags each line (`✓step` / `~wall`).
+
+**Migration:** none required. A plan whose steps carry no estimation data — or a
+plan with no steps at all — keeps working exactly as before via the fallback
+chain. Mixed plans (some steps estimated, some not) fall back to plan-level
+entirely rather than reporting a misleading partial sum.
+
+## Claims
+
+Claims make current ownership explicit.
+
+A claim can represent:
+
+- a file
+- a folder
+- a feature area
+- a work scope linked to a plan item
+
+Claims help reduce collisions when multiple humans or agents work in parallel.
+
+### Creating claims
+
+```bash
+brainclaw claim create "refactoring auth module" --scope src/auth/
+brainclaw claim create "updating docs" --scope docs/ --ttl 4h
+brainclaw claim create "fixing login bug" --scope src/auth/ --plan <plan-id>
+```
+
+The `--ttl` flag sets a time-to-live for the claim. After expiry, the claim is no longer considered active by other agents. Valid formats: `30min`, `2h`, `1d`.
+
+### Listing and releasing claims
+
+```bash
+brainclaw claim list
+brainclaw claim release <id>
+```
+
+`claim list` shows who holds each claim and whether it is still active. If a claim has a `session_id`, the last 8 characters are shown so you can correlate with the agent session that created it.
+
+### Automatic claim release
+
+Claims are automatically released after a `git merge` if the post-merge hook is installed (installed by default by `brainclaw init`). The hook matches merged file paths against active claim scopes and releases overlapping claims.
+
+You can also install or reinstall the hook manually:
+
+```bash
+brainclaw install-hooks
+```
+
+## Why claims matter
+
+Without claims, multiple agents can easily touch the same area at once and generate conflicting changes.
+Claims are not necessarily hard file locks.
+They are a shared coordination signal.
+
+## Policy checks
+
+Before editing a scope, agents can verify governance compliance using `check-policy`:
+
+```bash
+brainclaw check-policy --scope src/core/auth.ts --agent claude-code
+```
+
+Or via MCP:
+
+```
+bclaw_check_policy(scope: "src/core/auth.ts", agent: "claude-code")
+```
+
+The check is fully **deterministic** (no AI involved) and verifies:
+
+- **Claim active** — Does the agent have a claim on this scope? (BLOCK if not)
+- **Claim conflict** — Is another agent claiming this scope? (BLOCK)
+- **Constraints** — Do any active constraints with matching `related_paths` apply? (WARN)
+- **Traps** — Are there known pitfalls for this scope? (WARN)
+- **Governance context** — Active global instructions are surfaced for reference.
+
+Policy warnings are also **automatically included** in the `bclaw_claim` response — agents get constraint and trap alerts at claim time without an extra call.
+
+## Recommended workflow
+
+1. create a plan item
+2. claim the target scope — `bclaw_claim` (or `bclaw_work(intent="execute", scope=…, planId=…)`) creates an isolated git worktree under `~/.brainclaw/worktrees/<project-hash>/` automatically; policy warnings are surfaced as part of the response
+3. work on the implementation inside the worktree
+4. update the plan status (`bclaw_transition(entity="plan", id, to="in_progress" | "done")`)
+5. commit and merge back; release the claim when done or blocked
+6. create a handoff if another actor should continue
+
+## Session hygiene
+
+Before finishing a session, always:
+
+- release active claims: `brainclaw claim release <id>`
+- update plan items: `brainclaw plan update <id> --status done`
+- or use `brainclaw session-end --auto-release` to clean up automatically
+
+`session-end --auto-release` releases all claims held by the current agent and marks any `in_progress` plans as needing attention.
+
+## Plans + claims together
+
+Plans describe what should happen.
+Claims describe who is currently working where.
+
+That combination is much more useful than either one alone.

package/docs/concepts/project-md-convention.md

@@ -1,35 +1,35 @@
-# The PROJECT.md Convention (Instruction Layering)
-
-When working with AI agents, balancing **context freshness** against **context bloat** is an ongoing challenge. If you feed an agent too many rules, it consumes tokens and increases the risk of "lazy" behavior or hallucinated context loss.
-
-Brainclaw enforces a strict separation of concerns via "Instruction Layering":
-
-1. **Coordination Rules (The `brainclaw` context):** Managed completely by Brainclaw. This covers memory synchronization, plans, handoffs, and team coordination.
-2. **Domain Rules (The Project context):** Managed entirely by you. This covers tech stack features, architecture standards, UI guidelines, and test instructions.
-
-To link these two seamlessly, Brainclaw introduces the canonical **`PROJECT.md` Convention**.
-
-## The Mechanism
-
-Brainclaw treats the `PROJECT.md` file at the root of a workspace as the definitive source of truth for your domain rules. 
-
-When Brainclaw updates the surface instruction files for agents (`CLAUDE.md`, `copilot-instructions.md`, `.cursor/rules`, etc.), it automatically extracts and routes your project vision using a **hybrid injection technique**.
-
-### 1. The "Inject Content" Mode (Short Files, <=20 lines)
-If your `PROJECT.md` is concise and serves as a simple "pitch" for the project (under 20 lines), Brainclaw will literally copy its content into the agent surface files under the `## brainclaw — this project` header. 
-- **Benefit:** Zero tool calls required by the agent. It gets the pitch instantly on session start.
-
-### 2. The "Inject Pointer" Mode (Detailed Files, >20 lines)
-For larger, production-grade projects, your domain rules will easily exceed 20 lines. If Brainclaw injected 300 lines of coding guidelines into every agent prompt file, it would destroy your context window.
-Instead, when your `PROJECT.md` exceeds 20 lines, Brainclaw injects a rigid pointer:
-
-> **Project Domain Rules**
-> This project maintains detailed domain rules and architecture externally to avoid context bloat.
-> You MUST read `PROJECT.md` in the workspace root to understand the project constraints, tech stack, and conventions before coding.
-
-- **Benefit:** Prevents context bloat. The agent uses a targeted file read (`read_file`) only when necessary to acquire deep codebase context.
-
-## Best Practices
-
-- Always keep architecture guidelines, testing boundaries, and specific rules in `PROJECT.md` (or link out to other docs from it).
-- Never edit the `<!-- brainclaw:start -->` wrapped contents in surface files manually. They will be overwritten during the next `brainclaw export` cycle.
+# The PROJECT.md Convention (Instruction Layering)
+
+When working with AI agents, balancing **context freshness** against **context bloat** is an ongoing challenge. If you feed an agent too many rules, it consumes tokens and increases the risk of "lazy" behavior or hallucinated context loss.
+
+Brainclaw enforces a strict separation of concerns via "Instruction Layering":
+
+1. **Coordination Rules (The `brainclaw` context):** Managed completely by Brainclaw. This covers memory synchronization, plans, handoffs, and team coordination.
+2. **Domain Rules (The Project context):** Managed entirely by you. This covers tech stack features, architecture standards, UI guidelines, and test instructions.
+
+To link these two seamlessly, Brainclaw introduces the canonical **`PROJECT.md` Convention**.
+
+## The Mechanism
+
+Brainclaw treats the `PROJECT.md` file at the root of a workspace as the definitive source of truth for your domain rules. 
+
+When Brainclaw updates the surface instruction files for agents (`CLAUDE.md`, `copilot-instructions.md`, `.cursor/rules`, etc.), it automatically extracts and routes your project vision using a **hybrid injection technique**.
+
+### 1. The "Inject Content" Mode (Short Files, <=20 lines)
+If your `PROJECT.md` is concise and serves as a simple "pitch" for the project (under 20 lines), Brainclaw will literally copy its content into the agent surface files under the `## brainclaw — this project` header. 
+- **Benefit:** Zero tool calls required by the agent. It gets the pitch instantly on session start.
+
+### 2. The "Inject Pointer" Mode (Detailed Files, >20 lines)
+For larger, production-grade projects, your domain rules will easily exceed 20 lines. If Brainclaw injected 300 lines of coding guidelines into every agent prompt file, it would destroy your context window.
+Instead, when your `PROJECT.md` exceeds 20 lines, Brainclaw injects a rigid pointer:
+
+> **Project Domain Rules**
+> This project maintains detailed domain rules and architecture externally to avoid context bloat.
+> You MUST read `PROJECT.md` in the workspace root to understand the project constraints, tech stack, and conventions before coding.
+
+- **Benefit:** Prevents context bloat. The agent uses a targeted file read (`read_file`) only when necessary to acquire deep codebase context.
+
+## Best Practices
+
+- Always keep architecture guidelines, testing boundaries, and specific rules in `PROJECT.md` (or link out to other docs from it).
+- Never edit the `<!-- brainclaw:start -->` wrapped contents in surface files manually. They will be overwritten during the next `brainclaw export` cycle.

package/docs/concepts/runtime-notes.md

@@ -1,38 +1,38 @@
-# Runtime Notes
-
-Runtime notes capture operational observations made during work.
-
-They help bridge the gap between live execution and durable project memory.
-
-## Examples
-
-- a local environment quirk
-- a host-specific issue
-- a temporary blocker
-- a short-lived implementation observation
-- a note worth later reflection
-
-## Visibility modes
-
-Depending on configuration and use, runtime notes may be:
-
-- shared
-- machine-local
-- private
-
-This lets teams keep transient or host-specific context available without polluting canonical project memory too early.
-
-## Reflection workflow
-
-A runtime note does not have to become durable memory immediately.
-A useful pattern is:
-
-1. capture the observation quickly
-2. keep it visible in runtime state
-3. reflect it into a candidate if it seems reusable
-4. accept or reject it later through review
-
-## Why this matters
-
-This creates a safer bridge from ephemeral facts to durable memory.
-Not every operational observation deserves instant promotion.
+# Runtime Notes
+
+Runtime notes capture operational observations made during work.
+
+They help bridge the gap between live execution and durable project memory.
+
+## Examples
+
+- a local environment quirk
+- a host-specific issue
+- a temporary blocker
+- a short-lived implementation observation
+- a note worth later reflection
+
+## Visibility modes
+
+Depending on configuration and use, runtime notes may be:
+
+- shared
+- machine-local
+- private
+
+This lets teams keep transient or host-specific context available without polluting canonical project memory too early.
+
+## Reflection workflow
+
+A runtime note does not have to become durable memory immediately.
+A useful pattern is:
+
+1. capture the observation quickly
+2. keep it visible in runtime state
+3. reflect it into a candidate if it seems reusable
+4. accept or reject it later through review
+
+## Why this matters
+
+This creates a safer bridge from ephemeral facts to durable memory.
+Not every operational observation deserves instant promotion.