@brainfile/cli 0.13.3 → 0.15.1

package/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.1] - 2026-02-19
+
+### Added
+- **Workspace format probe for migration readiness**
+  - New shared detector classifies workspaces as `v2`, `legacy-root`, `legacy-dotbrainfile`, `mixed`, or `empty`
+  - Used consistently by init/migrate/hint flows to avoid command drift
+- **Soft migration warnings in TUI read path**
+  - Launching `brainfile tui` in legacy/mixed workspaces now shows a non-blocking upgrade hint
+
+### Changed
+- **`brainfile migrate` is now the primary v2 upgrade path**
+  - Migration now handles legacy root and legacy `.brainfile/brainfile.md` layouts in one command
+  - Mixed workspaces are handled safely (including backup of stray legacy root files)
+  - Existing `board/`/`logs/` partial states are recognized and migrated more robustly
+- **Migration guidance text now points to `brainfile migrate` (without `--v2`)**
+  - Updated CLI hints and relevant command errors/messages
+
+### Fixed
+- **`brainfile init` legacy detection behavior**
+  - `init` now refuses to initialize over detected legacy/mixed layouts and suggests running `brainfile migrate`
+  - Already-v2 workspaces are treated idempotently (no destructive re-init path)
+- **List/TUI migration nudges**
+  - `brainfile list` and `brainfile tui` now provide soft warnings when legacy layout is detected, improving discoverability for required migration
+
+## [0.14.0] - 2026-02-18
+
+### Added
+- **Per-task file architecture (v2)** - Tasks are now individual `.md` files instead of embedded YAML
+  - `brainfile init` creates v2 structure: `brainfile.md` (config), `tasks/`, `logs/`, `state.json`
+  - `brainfile migrate --v2` converts v1 boards to v2 per-task files (creates `.v1.bak` backup)
+  - All existing commands auto-detect v1 vs v2 and handle both transparently
+- **`brainfile complete`** - Move task from `tasks/` to `logs/` with `completedAt` timestamp
+  - Strips `column` and `position` fields from completed task
+  - `complete_task` MCP tool for parity
+- **`brainfile log`** - View and manage task history
+  - `brainfile log -t <id>` - View a completed task's log
+  - `brainfile log --search <query>` - Search across all completed task logs
+  - `brainfile log --recent` - List recently completed tasks
+  - `brainfile log note -t <id> "<message>"` - Append timestamped entry to any task's `## Log` section
+  - `search_logs` and `append_log` MCP tools for parity
+- **`brainfile search`** - Search across active tasks and completed logs with relevance scoring
+  - `search_tasks` MCP tool updated for v2
+
+### Changed
+- **All MCP tools have v2 support** - 29 tools detect v1/v2 and handle per-task files correctly
+  - Uses `@brainfile/core` as single source of truth for all task I/O operations
+  - CLI is a thin wrapper over core (no duplicated parsing/serialization logic)
+- **`brainfile init` defaults to v2** - Creates per-task file directory structure
+- Upgraded to @brainfile/core@^0.11.0
+
 ## [0.13.3] - 2026-01-01
 
 ### Added

package/README.md

@@ -1,450 +1,225 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/brainfile/cli/main/logo.png" alt="Brainfile Logo" width="128" height="128">
-</p>
-
 # @brainfile/cli
 
-**Task management for your terminal.** A full kanban board that lives in a markdown file.
-
-- Modern, borderless TUI optimized for information density
-- Vim-style navigation with intuitive keybindings
-- CLI commands for scripting and automation
-- MCP server for AI assistant integration
-
-## Installation
+**The official CLI for Brainfile.** Manage tasks, contracts, and ADRs directly from your terminal.
 
-```bash
-npm install -g @brainfile/cli
-```
+Designed for developers who want a local-first, file-based task management system that plays nicely with AI agents.
 
-Verify installation:
+## Install
 
 ```bash
-brainfile --version
+npm i -g @brainfile/cli
 ```
 
 ## Quick Start
 
-```bash
-# Initialize a new brainfile
-brainfile init
-
-# Launch interactive TUI
-brainfile
-
-# Or use CLI commands
-brainfile list                                    # List all tasks
-brainfile add --title "My task" --column todo     # Add a task
-brainfile move --task task-1 --column done        # Move a task
-```
-
-## Commands
-
-### Terminal UI (TUI)
-
-Launch an interactive task board:
+Initialize a new brainfile in your project root:
 
 ```bash
-brainfile                    # Auto-detect (prefers .brainfile/brainfile.md)
-brainfile ./path/to/file.md  # Open specific file
-```
-
-**Task Card Layout:**
-```
-  ▌ CRIT  Implement user authentication flow
-    [1/5] · Nov 30 · #auth #security                     task-39
-
-    HIGH  Dashboard performance optimization
-    [0/4] · Dec 4 · #performance #frontend               task-40
+brainfile init
 ```
 
-- `▌` indicator shows selected task
-- Priority badge (CRIT/HIGH/MED/LOW) leads each row
-- `[X/Y]` shows subtask progress
-- Due dates with urgency coloring (red if overdue, yellow if soon)
-- Tags and task ID complete the metadata row
-
-**Panel Navigation:**
-| Key | Action |
-|-----|--------|
-| `1` | Switch to Tasks panel |
-| `2` | Switch to Rules panel |
-| `3` | Switch to Archive panel |
-| `?` | Show help |
-| `q` | Quit |
-
-**Tasks Panel:**
-| Key | Action |
-|-----|--------|
-| `TAB` / `Shift+TAB` | Navigate columns |
-| `j`/`k` or `↑`/`↓` | Navigate tasks |
-| `h`/`l` or `←`/`→` | Switch columns |
-| `g`/`G` | Jump to top/bottom |
-| `Enter` | Expand/collapse task |
-| `/` | Search tasks |
-| `r` | Refresh |
-
-**Search Filters:**
-| Filter | Example | Description |
-|--------|---------|-------------|
-| Priority | `p:high` | Filter by priority |
-| Tag | `#bug` or `t:feature` | Filter by tag |
-| Assignee | `@john` | Filter by assignee |
-| Due date | `due:week` | `overdue`, `today`, `week`, `month` |
-
-Combine filters with text: `p:high #bug login issue`
-
-**Task Management:**
-| Key | Action |
-|-----|--------|
-| `e` | Edit task in $EDITOR |
-| `m` | Move task to column |
-| `d` | Delete task |
-| `n` | Quick add new task |
-| `N` | New task in $EDITOR |
-| `p` | Cycle priority |
-| `t` | Toggle subtask |
-| `A` | Archive task |
-| `y` | Copy task ID |
-
-**Rules Panel:**
-| Key | Action |
-|-----|--------|
-| `TAB` / `Shift+TAB` | Switch rule type |
-| `h`/`l` | Switch rule type (always/never/prefer/context) |
-| `j`/`k` | Navigate rules |
-| `n` | Add new rule |
-| `e` | Edit selected rule |
-| `d` | Delete selected rule |
-
-**Archive Panel:**
-| Key | Action |
-|-----|--------|
-| `j`/`k` | Navigate archived tasks |
-| `Enter` | Expand/collapse task |
-| `R` | Restore task to column |
-| `d` | Permanently delete task |
-| `r` | Refresh archive |
+This creates the standard v2 structure:
+- `.brainfile/brainfile.md` (Configuration, rules, definitions)
+- `.brainfile/board/` (Active tasks)
+- `.brainfile/logs/` (Completed tasks)
 
----
+The board comes pre-configured with `To Do` and `In Progress` columns.
 
-### list
+### Migrating older layouts
 
-List all tasks with optional filtering:
+If your repo still has a legacy `brainfile.md` layout, run:
 
 ```bash
-brainfile list
-brainfile list --column "In Progress"
-brainfile list --tag bug
+brainfile migrate
 ```
 
-**Options:**
-- `-f, --file <path>` - Brainfile path (default: `brainfile.md`)
-- `-c, --column <name>` - Filter by column
-- `-t, --tag <name>` - Filter by tag
-
----
+This upgrades your workspace to v2 (`.brainfile/brainfile.md` + `board/` + `logs/`).
 
-### show
+## Core Workflow
 
-Show full details of a single task:
+### Add Tasks
+Create new tasks with rich metadata.
 
 ```bash
-brainfile show --task task-1
-brainfile show -t task-1 --file ./brainfile.md
-```
+# Basic task
+brainfile add --title "Implement login" --column todo
 
-**Options:**
-- `-f, --file <path>` - Brainfile path (default: `brainfile.md`)
-- `-t, --task <id>` - Task ID (required)
+# Full featured task
+brainfile add \
+  --title "Refactor database layer" \
+  --type task \
+  --column todo \
+  --priority high \
+  --assignee @josh \
+  --tags "refactor,db" \
+  --parent epic-123
 
----
+# Create a parent with children in one shot
+brainfile add -c todo -t "Auth overhaul" \
+  --child "OAuth flow" --child "Session hardening"
+```
 
-### add
+**Key Flags:**
+- `--title, -t`: Task summary
+- `--type`: `task`, `epic`, or `adr` (default: `task`)
+- `--column, -c`: Target column ID
+- `--parent`: Parent task/epic ID
+- `--child`: Create child task(s) under the new parent (repeatable)
+- `--priority, -p`: `low`, `medium`, `high`, `critical`
+- `--tags`: Comma-separated list
 
-Create a new task:
+### List Tasks
+View your board from the command line.
 
 ```bash
-brainfile add --title "Implement auth" --column todo
-brainfile add --title "Fix bug" --priority high --tags "bug,urgent"
-brainfile add --title "Review PR" --assignee john --due-date 2025-02-01
+brainfile list                        # View all active tasks
+brainfile list --column todo          # Filter by column
+brainfile list --tag bug              # Filter by tag
+brainfile list --parent epic-123      # See all children of an epic
+brainfile list --contract ready       # See tasks with contracts waiting for pickup
 ```
 
-**Options:**
-- `-t, --title <text>` - Task title (required)
-- `-c, --column <name>` - Target column (default: `todo`)
-- `-d, --description <text>` - Task description
-- `-p, --priority <level>` - `low`, `medium`, `high`, or `critical`
-- `--tags <list>` - Comma-separated tags
-- `--assignee <name>` - Assignee name
-- `--due-date <date>` - Due date (YYYY-MM-DD)
-- `--subtasks <list>` - Comma-separated subtask titles
-
----
-
-### move
-
-Move a task to a different column:
+### Manage Tasks
+Manipulate tasks as you work.
 
 ```bash
-brainfile move --task task-1 --column "In Progress"
-brainfile move --task task-5 --column done
-```
+# View details
+brainfile show -t task-10
 
-**Options:**
-- `-t, --task <id>` - Task ID (required)
-- `-c, --column <name>` - Target column (required)
+# Move to another column
+brainfile move -t task-10 -c in-progress
 
----
+# Update fields
+brainfile patch -t task-10 --priority critical --tags "frontend,urgent"
 
-### patch
+# Clear fields
+brainfile patch -t task-10 --clear-tags --clear-assignee
 
-Update specific fields of a task:
-
-```bash
-brainfile patch --task task-1 --priority critical
-brainfile patch --task task-1 --title "Updated title" --tags "new,tags"
-brainfile patch --task task-1 --clear-assignee  # Remove assignee
+# Delete (permanently)
+brainfile delete -t task-10
 ```
 
-**Options:**
-- `-t, --task <id>` - Task ID (required)
-- `--title <text>` - New title
-- `--description <text>` - New description
-- `--priority <level>` - New priority
-- `--tags <list>` - New tags (comma-separated)
-- `--assignee <name>` - New assignee
-- `--due-date <date>` - New due date
-- `--clear-description` - Remove description
-- `--clear-priority` - Remove priority
-- `--clear-tags` - Remove tags
-- `--clear-assignee` - Remove assignee
-- `--clear-due-date` - Remove due date
-
----
-
-### delete
-
-Permanently delete a task:
+### Complete
+When a task is done, move it to the archive.
 
 ```bash
-brainfile delete --task task-1 --force
+brainfile complete -t task-10
 ```
+This moves the file from `.brainfile/board/` to `.brainfile/logs/`, preserving its history forever.
 
-**Options:**
-- `-t, --task <id>` - Task ID (required)
-- `--force` - Confirm deletion (required)
-
----
+## Types
 
-### archive
-
-Move a task to the archive:
+Brainfile supports different document types.
 
 ```bash
-brainfile archive --task task-1
+brainfile types list       # See available types (task, epic, adr)
+brainfile types add        # (Coming soon: define custom types)
 ```
 
----
+## Contracts: Working with AI Agents
 
-### restore
+Contracts allow you to define explicit deliverables and validation rules for AI agents.
 
-Restore a task from the archive:
+### 1. Create a Contract
+Add a task with a contract definition.
 
 ```bash
-brainfile restore --task task-1 --column todo
+brainfile add -c todo -t "Optimize image loader" \
+  --with-contract \
+  --deliverable "file:src/utils/loader.ts:Optimized implementation" \
+  --validation "npm test -- loader" \
+  --constraint "Must use lazy loading"
 ```
 
-**Options:**
-- `-t, --task <id>` - Task ID (required)
-- `-c, --column <name>` - Target column (required)
-
----
-
-### subtask
-
-Manage subtasks:
+### 2. Pickup (Agent)
+The agent claims the task.
 
 ```bash
-brainfile subtask --task task-1 --add "New subtask"
-brainfile subtask --task task-1 --toggle task-1-1
-brainfile subtask --task task-1 --update task-1-1 --title "Updated"
-brainfile subtask --task task-1 --delete task-1-2
+brainfile contract pickup -t task-45
 ```
+Status changes to `in_progress`. Metrics tracking begins.
 
-**Options:**
-- `-t, --task <id>` - Parent task ID (required)
-- `--add <title>` - Add a new subtask
-- `--toggle <id>` - Toggle subtask completion
-- `--update <id>` - Update subtask (use with `--title`)
-- `--delete <id>` - Delete a subtask
-- `--title <text>` - New title (for `--update`)
-
----
-
-### lint
-
-Validate and auto-fix brainfile syntax:
+### 3. Deliver (Agent)
+The agent marks work as ready for review.
 
 ```bash
-brainfile lint              # Check for issues
-brainfile lint --fix        # Auto-fix issues
-brainfile lint --check      # Exit with error code (for CI)
+brainfile contract deliver -t task-45
 ```
+Status changes to `delivered`.
 
-**What it checks:**
-- YAML syntax errors
-- Unquoted strings with colons (auto-fixable)
-- Duplicate column IDs
-- Missing required fields
-
----
-
-### template
-
-Create tasks from templates:
+### 4. Validate (User)
+Run the validation commands automatically.
 
 ```bash
-brainfile template --list
-brainfile template --use bug-report --title "Login fails"
-brainfile template --use feature-request --title "Dark mode"
+brainfile contract validate -t task-45
 ```
+- **Pass**: Task is marked `done`.
+- **Fail**: Task status reverts to `ready` (or `failed`) for rework.
 
-**Built-in Templates:**
-- `bug-report` - Bug tracking with triage steps
-- `feature-request` - Feature proposals
-- `refactor` - Code refactoring tasks
+## ADR Promotion
 
----
+Architecture Decision Records (ADRs) are first-class citizens. You can promote an accepted ADR to a global rule that agents must follow.
 
-### hooks
+```bash
+# 1. Create an ADR
+brainfile add -t "Use Postgres for all user data" --type adr -c proposed
 
-Integrate with AI coding assistants:
+# 2. Accept it (move to accepted column)
+brainfile move -t adr-1 -c accepted
 
-```bash
-brainfile hooks install claude-code
-brainfile hooks install cursor --scope project
-brainfile hooks install cline
-brainfile hooks list
-brainfile hooks uninstall claude-code --scope all
+# 3. Promote to a rule
+brainfile adr promote -t adr-1 --category always
 ```
 
-**Supported Assistants:**
-- Claude Code
-- Cursor
-- Cline
+**Categories:**
+- `always`: Strict rules (e.g., "Always use TypeScript")
+- `never`: Prohibitions (e.g., "Never commit secrets")
+- `prefer`: Guidelines (e.g., "Prefer functional components")
+- `context`: informational context
 
-Hooks provide automatic reminders to update task status during AI-assisted development.
+Promoted rules are added to `.brainfile/brainfile.md` and injected into agent prompts.
 
----
+## TUI (Terminal UI)
 
-### mcp
-
-Start an MCP (Model Context Protocol) server for AI assistant integration:
+Launch the interactive board:
 
 ```bash
-brainfile mcp
-brainfile mcp --file ./project/brainfile.md
+brainfile          # No arguments launches the TUI
+brainfile tui      # Explicit subcommand also works
 ```
 
-The MCP server exposes all brainfile operations as tools that AI assistants can use directly.
-
-**Available MCP Tools:**
-| Tool | Description |
-|------|-------------|
-| `list_tasks` | List tasks with optional filtering |
-| `add_task` | Create a new task |
-| `move_task` | Move task between columns |
-| `patch_task` | Update task fields |
-| `delete_task` | Permanently delete a task |
-| `archive_task` | Archive a task |
-| `restore_task` | Restore from archive |
-| `add_subtask` | Add a subtask |
-| `delete_subtask` | Delete a subtask |
-| `toggle_subtask` | Toggle subtask completion |
-| `update_subtask` | Update subtask title |
+### Panels
+- **Board (`1`)**: Kanban view of active tasks.
+- **Logs (`2`)**: List of completed tasks.
+- **Rules (`3`)**: Active rules and configuration.
 
-**Configuration for Claude Code:**
+### Keyboard Shortcuts
+| Key | Action |
+|-----|--------|
+| `tab` | Next column |
+| `j` / `k` | Down / Up |
+| `enter` | View task details |
+| `n` | New task |
+| `m` | Move task |
+| `e` | Edit task (in $EDITOR) |
+| `/` | Search |
+| `q` | Quit |
 
-Add to your MCP settings (`.mcp.json` or Claude Code config):
+## AI Integration
 
-```json
-{
-  "mcpServers": {
-    "brainfile": {
-      "command": "npx",
-      "args": ["@brainfile/cli", "mcp"]
-    }
-  }
-}
-```
+The CLI includes an MCP (Model Context Protocol) server.
 
-Or with a specific file:
+Add to your `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "brainfile": {
       "command": "npx",
-      "args": ["@brainfile/cli", "mcp", "-f", "path/to/brainfile.md"]
+      "args": ["@brainfile/cli", "mcp"]
     }
   }
 }
 ```
 
----
-
-### init
-
-Create a new brainfile:
-
-```bash
-brainfile init
-brainfile init --file ./project/tasks.md  # Custom location (optional)
-brainfile init --force  # Overwrite existing
-```
-
-### migrate
-
-Move a legacy root `brainfile.md` into the preferred `.brainfile/` directory:
-
-```bash
-brainfile migrate
-brainfile migrate --force
-```
-
-## Output Colors
-
-The CLI uses colors to highlight information:
-
-| Element | Color |
-|---------|-------|
-| Task IDs | Gray |
-| Titles | White |
-| Critical Priority | Red (bold) |
-| High Priority | Red |
-| Medium Priority | Yellow |
-| Low Priority | Blue |
-| Tags | Cyan |
-| Completed | Green |
-
-## Package Information
-
-- **npm**: https://www.npmjs.com/package/@brainfile/cli
-- **GitHub**: https://github.com/brainfile/cli
-- **Core Library**: [@brainfile/core](https://www.npmjs.com/package/@brainfile/core)
-- **Protocol**: https://brainfile.md
-
-## Development
-
-```bash
-git clone https://github.com/brainfile/cli.git
-cd cli
-npm install
-npm run build
-npm test
-```
-
-## License
-
-MIT
+This gives Claude (and other MCP clients) full access to read your board, create tasks, and manage contracts.