brainclaw 1.8.0 → 1.9.1

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

@@ -1,174 +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).
-
-## 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.

package/docs/concepts/skills.md

@@ -0,0 +1,78 @@
+# Skills — agent-profile vs workflow-protocol
+
+Brainclaw writes two orthogonal kinds of agent skill. The same agent can load
+both; they answer different questions.
+
+## Agent-profile skills
+
+The agent's **landing page** for brainclaw — one per agent profile
+(`openclaw`, `nanoclaw`, `nemoclaw`, `picoclaw`, `zeroclaw`) plus the universal
+`.agents/skills/brainclaw/SKILL.md` discovered by every agent that honors the
+shared `.agents/skills/` convention (Cursor, Copilot, Roo, OpenCode, Codex,
+Kilo, Mistral…). It answers *"what is brainclaw and how do I load context here?"*
+and points at `bclaw_work` as the entry verb.
+
+Source: `src/core/agent-files.ts` (`ensureUniversalBrainclawSkill`, the per-profile
+writers). These files are **generated, not committed** — they are gitignored and
+materialized by `brainclaw export` / setup, so the source of truth is the code,
+never a checked-in `SKILL.md`.
+
+## Workflow-protocol skills (pln#519)
+
+**Workflow-decomposed** skills that package a critical brainclaw protocol so the
+agent loads *the right one at the right moment* instead of skimming a monolithic
+AGENTS.md. Three ship today, namespaced `brainclaw-*`:
+
+| Skill | Trigger |
+|---|---|
+| `brainclaw-session` | starting / resuming / closing a session; before claiming a scope |
+| `brainclaw-memory-capture` | recording a decision / constraint / trap / handoff at the right type |
+| `brainclaw-multi-agent` | delegating, reviewing, dispatching, driving a loop |
+
+They carry `metadata.protocol: true` in frontmatter so skill-loader UIs can list
+protocols separately from profile skills, and `metadata.brainclaw_version` (set
+to `package.json:version` at write time) so a loader can detect a cached skill
+that predates a brainclaw upgrade. Each follows the "process not prose" shape:
+**When to use → Workflow → Anti-rationalizations → Red flags → Verification**.
+
+Source: `src/core/protocol-skills.ts` (single source of truth; content is
+embedded, not read from a repo file, so it installs identically from source or
+an npm install). Written to `.agents/skills/<id>/SKILL.md` by
+`ensureProtocolSkills`, wired into `writeDetectedAgentAutoConfig` for every agent
+whose capability profile declares `hasSkills: true`. Generated + gitignored, like
+the profile skills.
+
+### Design invariants
+
+- **No dynamic state.** A protocol-skill never embeds a concrete `claim_id` /
+  `loop_id` / `plan_id` — it tells the agent *when* to call a facade and *how to
+  read* live state, never *what the current state is*. (Enforced by a test.)
+- **Facade-only.** Skills reference canonical-grammar / facade verbs by name;
+  they never re-implement `mcp.ts` logic. A protocol change updates the skill,
+  not the other way round.
+- **Both MCP and CLI.** Each workflow shows the MCP call AND the `brainclaw …`
+  CLI fallback, because MCP is not always wired (cold start; a dispatched worker
+  in a worktree without `.brainclaw/`, trp#336).
+- **Capped at 3.** Setup and troubleshooting protocols are deferred until an
+  empirical friction shows the three are insufficient (design §E.2). A 4th
+  protocol needs a runtime_note documenting the gap it closes.
+
+## Namespace claim
+
+Brainclaw owns the `brainclaw-*` prefix under `.agents/skills/`. Other tools that
+install skills into the shared directory must avoid `brainclaw-` ids to prevent
+collisions.
+
+## Supply chain
+
+Protocol-skills ship **inside the npm package**. Brainclaw does **not** currently
+support installing external skills (no `brainclaw skill install <url>`, no loading
+from arbitrary paths). If external installs are ever added they will require a
+deliberate trust boundary (local-only or brainclaw-signed); that is out of scope
+today.
+
+## Staleness
+
+If `brainclaw --version` reports newer than a skill's `brainclaw_version`,
+re-run `brainclaw export --all --write` to regenerate. The version tag lets a
+caching loader detect drift; it does not self-heal.